Skip to main content

​
Understanding external contacts

External contacts are contacts that originate from outside the Quo app: either created through the Quo API or synced via native integrations (such as CRM or other connected platforms). These contacts allow you to centralize contact records from multiple sources within your Quo workspace.

​
Key characteristics

Distinct from app-created contacts

External contacts are separate from contacts created directly in the Quo app, with their own specific behaviors depending on how they were created.

Two sources, different behaviors

External contacts can come from two sources: the Quo API or native integrations and each has different editability rules within the Quo app.

​
Editability by source

API-created contacts

Contacts created via the Quo API can be updated directly within the Quo app. You can also continue managing them programmatically through API endpoints.

Native integration contacts

Contacts synced from native integrations remain read-only within Quo. Any changes must be made in the source system and synced back to Quo.

​
Important behaviors and limitations

Preserving contact IDs

When you create a 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 API operations involving the contact.

Visibility in the Quo app

After creating an API 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.

​
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 via API

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

Update contacts either within the Quo app or programmatically using the PATCH /contacts/:id endpoint with the saved contact ID.
Always validate phone numbers are in E.164 format (+1234567890) before creating or updating contacts to ensure proper functionality.