Skip to main content

​
Understanding integration contacts

Integration contacts are contacts that are created and managed through the Quo API. They provide a programmatic way to import contact records from external sources into your Quo workspace.

​
Key characteristics

Distinct from app contacts

Integration contacts are separate from contacts created directly in the Quo app, with their own specific behaviors and management flow.

API-first management

These contacts are designed to be managed exclusively through API endpoints, enabling automated contact management and integration with your existing systems. They cannot be modified or deleted within Quo.

​
Important behaviors and limitations

Preserving contact IDs

When you create an integration contact using the POST /contacts endpoint, it’s essential to save the id returned in the response. This id will be required for all future operations involving the contact.

Visibility in the Quo app

After creating an integration contact, it will only appear in the Quo app—whether in the conversation list, contact list, or search results—if there’s an associated conversation with a matching phone number.

Read-only status

At present, integration contacts are read-only within the Quo app. To make any updates or changes to an integration contact, you will need to use the PATCH /contacts/:id endpoint.

​
Contact field structure

Quo organizes contact information using two distinct field types. Understanding these is crucial for effective contact management.

Default fields

Every contact in Quo includes these predefined fields:
  • First Name
  • Last Name
  • Role
  • Company
  • Emails
  • Phone Numbers
These fields maintain consistent properties across all contacts and form the foundation of contact information.
Custom fields allow for flexible, user-defined contact properties. Supported data types include:
  • Address
  • Boolean
  • Date
  • Multi-select
  • Number
  • String
  • URL
Managing Custom Fields: Custom field definitions can only be modified within the Quo app. The API does not currently support creating or editing custom field definitions.

​
Creating and managing contacts

Follow these steps to effectively create and manage contacts through the API:
1

Retrieve custom fields

First, call the GET /contact-custom-fields endpoint to retrieve your workspace’s custom contact field definitions.
2

Prepare contact data

Structure your contact data according to both default and custom fields:
{
  "defaultFields": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumbers": [
      {
        "name": "primary",
        "value": "+1234567890"
      }
    ]
  },
  "customFields": {
    // Include any custom field values here
  }
}
3

Create the contact

Use the POST /contacts endpoint to create the contact and store the returned contact ID for future operations.
4

Manage the contact

Use the saved contact ID with the PATCH /contacts/:id endpoint for any future updates to the contact’s information.
Always validate phone numbers are in E.164 format (+1234567890) before creating or updating contacts to ensure proper functionality.
⌘I