Create contact

If you have questions regarding this API, please visit our API FAQ page.

Creating a contact

Make a POST request to https://webapi.inboxroad.com/api/v2/contacts-lists/{blueprint_id}/contacts/ with a valid X-API-Key.

curl -X POST 'https://webapi.inboxroad.com/api/v2/contacts-lists/{blueprint_id}/contacts/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "status": "subscribed",
    "plan": "pro"
  }'

Path parameters

Param name	Description
blueprint_id	Unique identifier of the contacts list (UUID).

Request fields

The always-present default fields:

Field name	Required	Description
email	Yes	Email address. Required and unique within the list. Max 150 chars.
first_name	No	First name. Max 50 chars.
last_name	No	Last name. Max 50 chars.
status	No	`subscribed` or `unsubscribed`. Defaults to `subscribed` if omitted.

Example request

{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "subscribed",
  "plan": "pro"
}

Here plan is a custom field defined on the list.

Response

On success the API returns 200 with the created contact record. The keys mirror the list’s field schema (defaults plus any custom fields).

{
  "id": 4821,
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "subscribed",
  "created_at": "2026-05-21T09:45:00Z",
  "plan": "pro"
}

Possible response codes

Status code	Description
200	Contact created successfully.
400	Invalid request data, or a contact with this email already exists. Body: `{ "errors": [ ... ] }`.
401	Unauthorized.
403	Adding contacts is not available for your account. Body: `{ "errors": [ ... ] }`.