Lead API

API Endpoint

curl -X POST -H "Content-Type: application/json" -d '{
    "crmListId": "abc123",
    "key": "your-api-key-for-the-client",
    "firstName": "John",
    "lastName": "Doe",
    "displayName": "John Doe",
    "email": "john.doe@example.com",
    "CustomFields": [
      {"fieldName": "customField1", "fieldValue": "value1"},
      {"fieldName": "customField2", "fieldValue": 42}
    ],
    "documents": [
      {"name": "Document 1", "document": "base64-encoded-data", "type": "pdf"}
    ]
  }'
  https://agency.xamtac.com/api/external-api/agency/leads/add-lead

Xamtac Agency CRM API

Overview

The provided code implements an API endpoint for adding leads to a Customer Relationship Management (CRM) system. The endpoint supports the addition of leads both with and without custom fields. The custom fields are defined by the CRM structure, and their presence and validity are verified during lead creation.

Endpoint Information

Endpoint URL: /api/external-api/agency/leads/add-lead
HTTP Method: POST

Request Parameters

The API accepts a JSON payload in the request body with the following parameters:

Common Parameters

crmListId(string, required): The identifier for the CRM list where the lead should be added.
key(string, required): API key for authentication.

Lead Information

firstName (string, optional): First name of the lead.
lastName (string, optional): Last name of the lead.
company (string, optional): Company name associated with the lead.
displayName (string, required): Display name for the lead.
email (string, optional): Email address of the lead.
website (string, optional): Website URL of the lead.
mainPhone (string, optional): Main phone number of the lead.
mobilePhone (string, optional): Mobile phone number of the lead.
workPhone (string, optional): Work phone number of the lead.
faxNumber (string, optional): Fax number of the lead.
addressLine1 (string, optional): Address line 1 of the lead.
addressLine2 (string, optional): Address line 2 of the lead.
postalCode (string, optional): Postal code of the lead's address.
city (string, optional): City of the lead's address.
state (string, optional): State of the lead's address.
startDate (date, optional): Start date associated with the lead.
endDate (date, optional): End date associated with the lead.

Custom Fields

customFields(array of objects, optional): An array of custom fields, each represented as an object with fieldName(string) and fieldValue (any type).

Documents

documents(array of objects, optional): An array of documents associated with the lead, each represented as an object with name (string), document(string), and type (enum: "pdf", "images", "zip").

Response

The API responds with a JSON object containing information about the success or failure of the lead creation:

success(boolean): Indicates whether the lead creation was successful.
message(string): Provides additional information about the outcome of the operation.
data(object): Contains the lead data if the creation was successful.

Error Handling

In case of errors, the API returns an HTTP status code indicating the nature of the error and a JSON object with relevant error details:

400 Bad Request: Incorrect or missing request parameters.
500 Internal Server Error: General server error, possibly related to the CRM configuration or API key.

Notes

Ensure that you have a valid API key and CRM list ID before making requests.
Custom fields and document types must conform to the CRM's predefined structures.
The API response includes detailed messages for debugging and error resolution.

CRM API