Contact

Manage individual contacts in your address book.

📄️Find contacts

Searches and retrieves contacts with flexible filtering and pagination. This endpoint has two distinct behaviors depending on the listIds parameter. When listIds is provided (comma-separated contact list IDs), it returns the distinct set of contacts that belong to those lists, with optional additional filters applied on top. When listIds is omitted, it searches across all contacts in your account matching the provided filters. Use notListIds to exclude contacts that belong to specific lists, which is useful for finding contacts not yet assigned to a target list. The search parameter performs a case-insensitive match against the contact name and other text fields. You can filter by gender, isValid (whether the phone number has been validated), communicationSupported (e.g., SMS, RCS, WHATSAPP), isTest (to find or exclude test contacts), phoneNumber (exact match), and email (exact match). Results are paginated: page is 0-based, limit defaults to 10 (maximum 1000). Use sortBy to choose the sort field (defaults to fullName) and sortOrder for asc or desc. The sortPriorityListId parameter causes contacts belonging to that specific list to appear first in the results, which is useful when displaying contacts with a primary list highlighted. To retrieve contacts for a specific list with a cleaner API, consider using GET /contacts/list/{listId}/contacts instead. Returns 500 if an unexpected server error occurs.

📄️Delete contacts

Deletes contacts from your account. This endpoint supports two mutually exclusive modes. Mode 1 (selective delete): Provide ids as a comma-separated list of contact IDs to delete specific contacts. When ids is present, the notIds parameter is ignored. Mode 2 (bulk delete with exclusions): Provide notIds as a comma-separated list of contact IDs to keep, and all other contacts in your account will be deleted. This operation permanently removes the contact records and also removes their associations with any contact lists. Deleted contacts will no longer be available as recipients for future campaigns. Delivery history for past campaigns that included these contacts is preserved. Use this with caution, especially Mode 2, as it can delete a large number of contacts in a single call. Returns 200 with the result of the deletion operation. Returns 500 if an unexpected server error occurs.

📄️Create a new contact

Creates a new individual contact in your account. You must provide at least a phone number or an email address. The phone number should be in E.164 international format (e.g., +393331234567). You can include optional fields such as firstName, lastName, gender, and any custom fields your account has configured. After creating a contact, you can assign it to one or more contact lists using POST /contacts/list/contacts so it becomes a recipient in campaigns. For bulk imports, use POST /contacts/upload (CSV/Excel) or POST /contacts/upload/vcard (VCF) instead of creating contacts one by one. Returns 201 with the created contact details including the generated contact ID. Returns 400 if the request body is missing required fields or contains invalid data (e.g., malformed phone number). Returns 500 if an unexpected server error occurs.

📄️Upload and parse a contact list file

Uploads a tabular file and imports its rows as contacts into your account. Supported file formats include CSV (.csv), Microsoft Excel (.xls, .xlsx), and other delimited text files. The file format is detected from the fileName extension. The file must be sent as multipart/form-data with the file in the 'file' field and the original filename in the 'fileName' field. Set removeHead=true if the first row of the file contains column headers that should not be imported as a contact record. The limit parameter controls how many parsed rows are returned in the response preview (defaults to 10) but does not limit the actual number of contacts imported. The import runs in CREATE_UPDATE mode: new contacts are created, and existing contacts (matched by phone number) are updated with the new data. If a listId is provided, all successfully imported contacts are automatically added to that contact list. Column mapping is performed automatically based on recognized header names (e.g., firstName, lastName, phoneNumber, email). Returns 400 if the file type is not supported, the file is corrupted, or the file cannot be parsed. Returns 500 if an unexpected server error occurs during import processing.

📄️Upload and parse a VCard file

Uploads a VCard (.vcf) file and imports its entries as contacts into your account. The file must be sent as multipart/form-data with the file in the 'file' field and the original filename (must have .vcf extension) in the 'fileName' field. VCard files can contain one or multiple contact entries. Each vCard entry is parsed and mapped to a contact record using standard vCard fields (FN, TEL, EMAIL, etc.). The import runs in CREATE_UPDATE mode: new contacts are created, and existing contacts (matched by phone number) are updated with the data from the VCard. If a listId is provided, all successfully imported contacts are automatically added to that contact list. The limit parameter controls how many parsed contacts are returned in the response preview (defaults to 10) but does not limit the actual number of contacts imported. This endpoint is particularly useful for importing contacts exported from phone address books, Outlook, Google Contacts, or other CRM tools that support the VCard standard. Returns 400 if the file does not have a .vcf extension or is not a valid VCard file. Returns 500 if an unexpected server error occurs during import processing.

📄️Update a contact

Updates an existing contact identified by its numeric ID. You can modify any contact field: name, phone number, email, gender, custom fields, etc. Only the fields provided in the request body will be updated; omitted fields remain unchanged. Use GET /contacts/{id} first to retrieve the current values if you need to perform a partial update and want to preserve existing data. Updating a contact phone number may affect its validity status and communication capabilities (e.g., a new number might not support RCS). Contact list memberships are not affected by this endpoint; use the /contacts/list/contacts endpoints to manage list associations. Returns 200 with the updated contact details. Returns 400 if the request body contains invalid data. Returns 404 if no contact exists with the given ID under your account. Returns 500 if an unexpected server error occurs.

📄️Get contact by ID

Retrieves the full details of a single contact by its numeric ID. The response includes all stored fields: name, phone number, email, gender, validity status, communication capabilities, custom fields, and any associated contact list memberships. Use this endpoint to inspect a contact record before updating it with PUT /contacts/{id}, or to verify the details of a contact after creation. Returns 404 if no contact exists with the given ID under your account. Returns 500 if an unexpected server error occurs.