NUACOM API

Contacts & CRM

Contacts

Contacts are the account's phonebook: the names shown on inbound calls, the entries behind click-to-call, SMS recipients and the source for CRM matching. A contact has up to five phone numbers, an optional email and address, and belongs to any number of groups and organizations. It is either shared with the whole account or private to the user who owns it.

Contacts have two endpoint families: /v3/contacts…, which the NUACOM portal uses throughout and which you should prefer, and the older /v2/contacts…, which has the same request and response shape but a narrower perPage choice and is not used by any NUACOM client.

Workflow (what the portal does)

  1. List and search: GET /v3/contacts with page, perPage (1–500), sort (-id by default in the portal; first_name, last_name, email, organization are also allowed), and filter[...]: search (name, number, email or organization), visibility (all, public, private), group[], organization[], plus exact or ~-prefixed partial matches on individual fields. Unknown filters and sorts answer 400.
  2. Create: POST /v3/contacts with first_name or last_name, phones[] (international format, at most five) or email, optional address_1…address_4, post_code, country (ISO 3166-1 alpha-2), comments, birthdate, groups[], organizations[] and private. Pick group and organization ids from GET /v3/contacts/groups and GET /v3/contacts/organizations.
  3. Read and edit: GET /v3/contacts/{contactId}, then PUT /v3/contacts/{contactId} with the complete contact: the update replaces every phone and address field with what you send.
  4. Group and organization membership: PUT /v3/contacts/{contactId}/groups replaces a contact's groups; POST /v3/groups/contacts/bulk adds many contacts to many groups; POST /v3/contacts/organizations/bulk and DELETE /v3/contacts/organizations/bulk do the same for organizations.
  5. Visibility: POST /v3/contacts/bulk/visibility with contacts[] and visible shares a contact (true) or makes it private to you (false).
  6. Delete: DELETE /v3/contacts/{contactId} for one contact, DELETE /v3/contacts with contacts[] for many. Deletes are soft: filter[trashed]=with or only shows deleted contacts.
  7. Bulk import: POST /v3/contacts/import with a CSV, XLS or XLSX file and the 0-based column indexes (first_name_index, last_name_index, phone_indexes[], email_index, …), optional group_ids[] and private_user_id. Up to 100 rows are processed in the request; larger files answer isAsync: true with an importId to poll at GET /v3/contacts/import/status/{importId} (pending, processing, completed, failed, with progress).
  8. Export: GET /v3/contacts/export accepts the list's filter and sort, builds the CSV in the background and emails it to the requesting user (204).

Related: GET /v3/contacts/activity returns a contact's recent calls and SMS; GET /v2/phonebook/name-by-number resolves a number to a shared contact's name (cached for 24 hours); the inbound call log carries the contact id and name of each call.

Roles and access

  • Every endpoint above is open to any authenticated user of the account. Handing one user's private contacts to another before that user is deleted is done in the portal when the user is removed.
  • Private contacts of other users are hidden from the list, the export and show (which answers 404). An API key sees the contacts its creator sees.

Pitfalls

  • Phone numbers are stored as digits with the country code and no + (353861234567), and are returned that way in phones[].phone_number. Send them in international format (+353861234567 or 00353…) when creating or updating; a national number such as 0861234567 fails validation. The importer is more lenient and reads numbers in the user's country.
  • There is no duplicate detection: creating or importing the same person twice gives two contacts.
  • PUT is a full replacement. Omitting email, comments or the address clears them; omitting private makes the contact shared.
  • perPage differs: /v3/contacts accepts 1–500, /v2/contacts only 15, 50, 100 or -1 ("all", capped at 1000 rows, 422 above that).
  • Names imported from files are HTML-encoded (O'Brien); decode them client-side.
  • A row is imported only if it has a name and at least one valid number; email-only rows are skipped, unlike manual creation. POST /v3/contacts/import skips the header row, POST /v2/phonebook/import does not.
  • The export CSV holds only the first mobile and the first landline of each contact.