Create Contact via Assistable API

Objective: To programmatically create a new contact record within a specific location using the Assistable API. This is the primary method for ingesting leads from forms, external CRMs, or manual triggers.

1. Endpoint Configuration

HTTP Method: POST
Base URL: https://api.assistable.ai/v2/contacts/create-contact/
Path Parameter: :id (This corresponds to the location_id)

Full Request URL:

https://api.assistable.ai/v2/contacts/create-contact/{location_id}

2. Payload Preparation (Request Body)

The request body must be formatted as JSON. Below is the schema and the description of key fields.

Field	Type	Requirement	Description
`first_name`	String	Optional	The contact's given name.
`last_name`	String	Optional	The contact's family name.
`phone_number`	String	Recommended	E.164 format (e.g., +17702967272). Essential for SMS workflows.
`email`	String	Recommended	Valid email address. Essential for email workflows.
`tags`	Array	Optional	List of strings. Critical for triggering workflows.
`custom_fields`	Object	Optional	Key-value pairs for custom data (e.g., `{"age": 30}`).

Example JSON Payload

JSON

{
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+17702967272",
  "email": "jordsen@assistable.ai",
  "tags": [
    "lead-form-submitted",
    "priority-high"
  ],
  "meta": {},
  "custom_fields": {
    "source": "website"
  },
  "attribution": {},
  "integration": {},
  "dnd": {}
}

Note on Workflow Triggers: To ensure downstream AI prompts or workflows react differently to specific contacts, populate the "tags" array (e.g., ["ai-follow-up"]).

3. Execution Steps

Identify Location ID: Retrieve the location_id for the target workspace. This replaces the :id in the URL.
Construct Payload: Map your source data (form fields) to the JSON structure above.
Send Request: Execute the POST request using your preferred client (cURL, Python requests, Postman, etc.).
Validate Response: Ensure the API returns a 200 OK or 201 Created status and a JSON object containing a valid "id".

4. Response Verification

A successful request will return the created contact object. You should store the id returned in this response if you plan to update this contact later.

Success Response Example:

JSON

{
    "id": "3aaaac27-d1dc-4a53-ab01-dd9b887e426f",
    "workspace_id": "test-workspace",
    "location_id": "test-location",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+17702967272",
    "email": "jordsen@assistable.ai",
    "tags": [
        "lead-form-submitted",
        "priority-high"
    ],
    "created_at": "2025-12-03T19:07:15.01671+00:00",
    "updated_at": "2025-12-03T19:07:15.01671+00:00"
}

5. Troubleshooting

400 Bad Request: Check that your JSON is valid and that phone_number or email formats are correct.
401 Unauthorized: Verify your API Key/Bearer Token is present in the headers.
404 Not Found: Verify the location_id in the URL is correct.