Contacts API

Learn how to manage contacts in AchieveApex using the REST API.

Overview

The Contacts API allows you to manage contacts within your organization. You can list, retrieve, create, update, and delete contacts.

Base Endpoint

/contacts

Contact Object

The contact object contains information about a contact in your organization.

Contact Object

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "1234567890",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "company_id": 101,
  "channel_whatsapp_wa_id": null,
  "channel_instagram_user_id": null,
  "system_type": "contact",
  "avatar_url": "/path/to/avatar.jpg",
  "custom_fields_by_name": {
    "Industry": "Technology",
    "Preferred Contact Method": "Email"
  }
}

List Contacts

Retrieve a list of contacts for your organization with optional filtering and pagination.

Request

GET /contacts

curl -X GET https://api.achieveapex.com/contacts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 456,
      "$limit": 25,
      "$skip": 0,
      "$sort": { "created_at": -1 },
      "fastJoinForContactList": true
    }
  }'

Response

{
  "total": 100,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "1234567890",
      "phone_country_code": "+1",
      "phone_country_iso": "US",
      "organization_id": 456,
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "deleted_at": null,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "company_id": 101,
      "owner": {
        "id": 789,
        "first_name": "Admin",
        "last_name": "User"
      },
      "company": {
        "id": 101,
        "name": "Example Corp"
      },
      "custom_fields_by_name": {
        "Industry": "Technology",
        "Preferred Contact Method": "Email"
      }
    },
    // Additional contacts...
  ]
}

Query Parameters

Parameter	Type	Description
organization_id	Number	ID of the organization to fetch contacts for (required)
$limit	Number	Number of contacts to return (default: 10)
$skip	Number	Number of contacts to skip (for pagination)
$sort	Object	Sort criteria (e.g., `{ "created_at": -1 }` for newest first)
fastJoinForContactList	Boolean	Include associated data like company and owner (recommended)

Get a Contact

Retrieve a single contact by ID.

Request

GET /contacts/:id

curl -X GET https://api.achieveapex.com/contacts/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "1234567890",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "company_id": 101,
  "channel_whatsapp_wa_id": null,
  "channel_instagram_user_id": null,
  "system_type": "contact",
  "avatar_url": "/path/to/avatar.jpg",
  "custom_fields_by_name": {
    "Industry": "Technology",
    "Preferred Contact Method": "Email"
  }
}

Create a Contact

Create a new contact in your organization.

Request

POST /contacts

curl -X POST https://api.achieveapex.com/contacts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "9876543210",
    "phone_country_code": "+1",
    "phone_country_iso": "US",
    "owned_by_user_id": 789,
    "company_id": 101
  }'

Response

{
  "id": 456,
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "9876543210",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "organization_id": 456,
  "created_at": "2023-01-02T00:00:00.000Z",
  "updated_at": "2023-01-02T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "company_id": 101,
  "channel_whatsapp_wa_id": null,
  "channel_instagram_user_id": null,
  "system_type": "contact",
  "avatar_url": null
}

Request Parameters

Parameter	Type	Required	Description
organization_id	Number	Yes	ID of the organization to create the contact in
first_name	String	Yes	First name of the contact
last_name	String	No	Last name of the contact
email	String	No	Email address of the contact
phone	String	No	Phone number of the contact
phone_country_code	String	No	Country code for the phone number (e.g., "+1")
phone_country_iso	String	No	ISO code for the phone country (e.g., "US")
owned_by_user_id	Number	No	ID of the user who owns this contact
company_id	Number	No	ID of the company associated with this contact

Update a Contact

Update an existing contact by ID.

Request

PATCH /contacts/:id

curl -X PATCH https://api.achieveapex.com/contacts/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.updated@example.com",
    "phone": "5551234567",
    "company_id": 102
  }'

Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.updated@example.com",
  "phone": "5551234567",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-03T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "company_id": 102,
  "channel_whatsapp_wa_id": null,
  "channel_instagram_user_id": null,
  "system_type": "contact",
  "avatar_url": "/path/to/avatar.jpg",
  "custom_fields_by_name": {
    "Industry": "Technology",
    "Preferred Contact Method": "Email"
  }
}

Delete a Contact

Delete a contact by ID. This is a soft delete that sets the deleted_at field.

Request

DELETE /contacts/:id

curl -X DELETE https://api.achieveapex.com/contacts/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.updated@example.com",
  "phone": "5551234567",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-04T00:00:00.000Z",
  "deleted_at": "2023-01-04T00:00:00.000Z",
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "company_id": 102,
  "channel_whatsapp_wa_id": null,
  "channel_instagram_user_id": null,
  "system_type": "contact",
  "avatar_url": "/path/to/avatar.jpg"
}

Search Contacts

Search for contacts by name, email, or phone number.

Request

POST /contacts
Headers: X-Service-Method: search

curl -X POST https://api.achieveapex.com/contacts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Service-Method: search" \
  -d '{
    "searchTerm": "john",
    "organization_id": 456,
    "$limit": 5,
    "searchIn": "name"
  }'

Response

{
  "total": 2,
  "limit": 5,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "1234567890",
      "phone_country_code": "+1",
      "phone_country_iso": "US",
      "organization_id": 456,
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "deleted_at": null,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "company_id": 101
    },
    {
      "id": 124,
      "first_name": "Johnny",
      "last_name": "Smith",
      "email": "johnny.smith@example.com",
      "phone": "9876543210",
      "phone_country_code": "+1",
      "phone_country_iso": "US",
      "organization_id": 456,
      "created_at": "2023-01-02T00:00:00.000Z",
      "updated_at": "2023-01-02T00:00:00.000Z",
      "deleted_at": null,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "company_id": 102
    }
  ]
}

Search Parameters

Parameter	Type	Required	Description
searchTerm	String	Yes	The term to search for (minimum 2 characters)
organization_id	Number	Yes	ID of the organization to search contacts in
$limit	Number	No	Maximum number of results to return
searchIn	String	Yes	Field to search in (options: "name", "email", "phone")
phone_country_iso	String	No	ISO code for phone country (required when searchIn is "phone")
phone_country_code	String	No	Country code for phone (required when searchIn is "phone")

Error Handling

The Contacts API returns standard HTTP status codes and error messages.

Error Response

{
  "name": "BadRequest",
  "message": "Invalid contact data",
  "code": 400,
  "className": "bad-request",
  "errors": {
    "email": "Invalid email format"
  }
}

Status Code	Description
400 Bad Request	Invalid request data
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Not authorized to access this contact
404 Not Found	Contact not found
500 Internal Server Error	Server error

Report an issue with this documentation

Please log in to report issues with our documentation.