Contacts

Base path: https://api.recepta.ai/api/v1/api/contacts All endpoints require an API key in x-api-key, and the permission noted on each.

List contacts

contacts:read

required

Query param	Type	Default	Notes
`page`	integer	`1`	Page number
`limit`	integer	`50`	Items per page
`search`	string	—	Matches name, email, or phone
`source`	enum	—	`MANUAL`, `FACEBOOK`, `CSV`, `API`, `CALL`
`status`	string	—	Filter by status
`tags`	string	—	Filter by tag

curl "https://api.recepta.ai/api/v1/api/contacts?source=FACEBOOK&limit=50" \
  -H "x-api-key: $RECEPTA_API_KEY"

Get a contact

contacts:read

required

Returns 404 if the contact isn’t in your workspace.

Create a contact

contacts:create

required

string

Use instead of first and last name where you only have a single field.

string

Normalized to E.164 automatically, so mixed input formats are accepted.

enum

default:"API"

One of MANUAL, FACEBOOK, CSV, API, CALL.

string[]

How you segment for campaigns. Tag on creation — retrofitting tags later is painful.

string

object

Anything specific to your business — equipment model, plan tier, gate code. Usable for personalization in sequences.

curl -X POST https://api.recepta.ai/api/v1/api/contacts \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Dana",
    "lastName": "Reyes",
    "phone": "+14155551234",
    "email": "dana@example.com",
    "source": "API",
    "tags": ["quotes-q3"],
    "customFields": { "unitModel": "AO-50G" }
  }'

Returns 201 on success.

Update a contact

contacts:update

required

Accepts the same fields as create.

curl -X PUT https://api.recepta.ai/api/v1/api/contacts/CONTACT_ID \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "booked", "tags": ["quotes-q3", "won"] }'

Delete a contact

contacts:delete

required

Deletion is permanent. Deleting a contact does not clear a suppression — someone who opted out of SMS or email stays suppressed, which is the intended behavior. Re-creating them will not re-enable messaging.

Keeping systems in sync

Subscribe to contact.created and contact.updated rather than polling this endpoint. See Webhooks.

Before bulk-creating contacts, check whether CSV import or a native CRM integration does the job. Both handle deduplication and mapping you’d otherwise write yourself.

Overview

Endpoints

Automation

List contacts

Get a contact

Create a contact

Update a contact

Delete a contact

Keeping systems in sync

​List contacts

​Get a contact

​Create a contact

​Update a contact

​Delete a contact

​Keeping systems in sync

List contacts

Get a contact

Create a contact

Update a contact

Delete a contact

Keeping systems in sync