Create contact

If you have questions about the API, please visit our API FAQ page.

Create a contact

Send a POST request to:

https://webapi.inboxroad.com/api/v2/contacts-lists/{blueprint_id}/contacts/

Authentication is required using the X-API-Key header.

Example request

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

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

Request fields

The following default fields are always available:

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

Custom fields

In addition to the default fields above, you may include any custom fields configured for the contacts list.

Extra fields are validated against the list’s field schema.

Use Get contact list to retrieve the available fields, their column_name values, and supported data types.

Caution

The ip and created_at fields are automatically set by the system.

If these fields are included in the request body, they are ignored.

Full JSON example

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

In this example, plan is a custom field defined on the contacts list.

Response

When the contact is created successfully, the API returns 200 with the created contact record.

The response contains the default fields together with any configured 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	A contact with this email already exists in the list, or a custom field failed the list’s schema.
401	Unauthorized.
403	Adding contacts is not available for your account.
404	Contact list not found.
422	blueprint_id is not a valid UUID, or the body failed validation (e.g. malformed email).
429	Rate limit exceeded. See Rate limiting.