Fetch Contact Person
Revision as of 15:50, 21 July 2026 by Ashley DeBon (talk | contribs) (Created page with "== Fetch Contact Person == === Base URL === https://apimobile.callproof.com === Endpoint === /api/ai/chat-bot/fetch-contact-person === Purpose === Resolves a contact and re...")
Contents
Fetch Contact Person
Base URL
https://apimobile.callproof.com
Endpoint
/api/ai/chat-bot/fetch-contact-person
Purpose
Resolves a contact and related person (personnel) from a company name and/or person name—typically used by the AI chat bot to find the right contact for messaging (for example, “Sarah from XYZ Corp”). Returns contact, person, and phone identifiers when a unique match is found; otherwise returns clarifying error details when multiple matches exist.
HTTP Method
POST
Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer access token |
Security
- Yes – Requires Bearer Token authentication.
Parameters
Path Parameters
None.
Query Parameters
None.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| companyId | integer | Yes | Company identifier to search within |
| contactName | string | No | Contact/company name to match (exact name match, case-insensitive) |
| personName | string | No | Person name to match against first/last name (partial match; supports one or two name parts) |
Successful Response (200)
Returned when a unique contact/person/phone match is resolved.
| Field | Type | Description |
|---|---|---|
| clientStatusCode | integer | Status indicator for the client (for example, 200) |
| user_id | integer | Identifier of the authenticated user |
| company_id | integer | Identifier of the authenticated user’s company |
| data | object | Resolved contact/person/phone details |
| uri | string | Requested resource URI |
data
| Field | Type | Description |
|---|---|---|
| contact_personal_id | integer | Unique identifier of the matched person (personnel) |
| contact_personal_name | string | Full name of the matched person |
| contact_phone_id | integer | Phone record identifier to use |
| contact_id | integer | Unique identifier of the matched contact |
Error Responses
| Status Code | Meaning |
|---|---|
| 200 | Validation failed – response body uses clientStatusCode 422 with the first validation error message
|
| 400 | Bad Request – contact/person could not be uniquely resolved (response includes message and optional data)
|
| 401 | Unauthorized – missing, invalid, or expired Bearer token |
- Validation (HTTP 200, clientStatusCode 422) – Missing or invalid
companyId. - 400 – Examples: invalid contact name ("contact name invalid"), contact not found, contact phone not found, multiple people with the same name, multiple companies with the same name, multiple contacts with the same name, or multiple phone numbers for the contact. Ambiguous matches may include a
datapayload listing candidates. - 401 – Authentication failed or the access token is missing/expired.
