--- title: "Create or update contacts in a batch" method: POST path: "/entities/Contacts/batch-modify" tags: ["Contact"] --- # Create or update contacts in a batch `POST /entities/Contacts/batch-modify` ## Request - Base URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id` - URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id/entities/Contacts/batch-modify` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) An item with an `id` updates that contact; an item without one creates a contact. By default one invalid item fails the whole call with HTTP 422; with `rollback-method=1` the response has an id or an error for each item, in input order. ## Query parameters - `validation-level` integer - `rollback-method` 0 | 1 ## Request body - BatchContactInput[] - `created` string, date-time: Creation time. - `picture` object: Profile picture associated with the contact. Related CloudObject record; see 'updateCloudObjectInput' for its fields. - `id` string, uuid: Id of the related CloudObject record. - `address` string: Street address of the contact. - `city` string: City of the contact address. - `comments` string: Free-form notes describing the contact. - `contact_type_id` string, uuid: Id of the contact type assigned to this contact. - `country` string: Country of the contact address. - `currency_exchange_rates_list_id` string, uuid: Id of the currency exchange rate list applied to this contact. - `email1` string: Primary email address of the contact. Used as default recipient for emails sent from Coevera. - `email2` string: Additional email address. - `email3` string: Additional email address. - `email4` string: Additional email address. - `email5` string: Additional email address. - `first_name` string: Given name of the contact. - `gender` 0 | 1 | 2 | 3: Gender of the contact: Unknown when not specified, Male, Female or NonBinary. Integer enum value: 0 - Unknown, 1 - Male, 2 - Female, 3 - NonBinary - `is_archived` boolean: True when the contact has been archived. Archived contacts remain readable but are hidden from active lists and cannot be edited until reactivated. - `last_name` string: Family name of the contact. - `middle_name` string: Middle name of the contact, if applicable. - `owner_id` string, uuid: Id of the contact owner. - `phone1` string: Primary phone number of the contact. Used as default target for click-to-call. - `phone2` string: Additional phone number. - `phone3` string: Additional phone number. - `phone4` string: Additional phone number. - `phone5` string: Additional phone number. - `picture_id` string, uuid: Id of the profile picture document. - `position` string: Job title or position of the contact. - `quick_account_name` string: Free-text company name used when the contact is not linked to an actual Account record. Lets integrators capture the company without creating a separate Account. - `share_mode` 0 | 1 | 2 | 3: Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `state_province` string: State or province of the contact address. - `title` string: Honorific or salutation prefix (e.g. Mr., Ms., Dr.) shown before the name. - `unit_id` string, uuid: Id of the sales unit. - `zip_code` string: ZIP or postal code of the contact address. - `revision` integer: Revision when entity was lastly changed. - `social_media` object: Social network profiles linked to this contact (e.g. LinkedIn, Facebook). Related ContactSocialRelation record; see 'updateContactSocialRelationInput' for its fields. - `id` string, uuid: Id of the related ContactSocialRelation record. - `account_relations` object[]: Accounts this contact is linked to. Each link records the role and position the contact has at the related account. - `id` string, uuid: Id of the related ContactAccountRelation record. - `sharing_units` object[]: Sales units that have been granted shared access to this contact. Editable only when share_mode allows unit sharing. - `id` string, uuid: Id of the related ContactSharingSalesUnitRelation record. - `sharing_clients` object[]: Users that have been granted shared access to this contact. Editable only when share_mode allows user sharing. - `id` string, uuid: Id of the related ContactSharingClientRelation record. - `documents` object[]: Documents linked to this contact. - `id` string, uuid: Id of the related CloudObjectRelation record. - `exchange_entity_id` string: External identifier of the record in the linked third-party service (e.g. Google, Microsoft 365, Exchange). Maintained by the sync engine. - `gapi_entity_id` string: External identifier of the record in the linked third-party service (e.g. Google, Microsoft 365, Exchange). Maintained by the sync engine. - `o365_entity_id` string: External identifier of the record in the linked third-party service (e.g. Google, Microsoft 365, Exchange). Maintained by the sync engine. - `primary_account_account_roles` object[]: Roles of Contact in his primary Account. - `id` string, uuid: Id of the related ContactAccountAccountRoleRelation record. - `account_position` string: Job position of Contact in his primary Account or quick account position if Contact has no primary Account. - `is_unsubscribed` boolean: If account has any unsubscribed email. - `tags` object[]: Tag labels applied to this contact. - `id` string, uuid: Id of the related TagRelation record. - `static_profiles` object[]: Saved view profiles this contact currently matches. - `id` string, uuid: Id of the related ProfileRelation record. - `primary_account_relationship` string: Org chart relationship of Contact in his primary Account. - `id` string, uuid: ID of object to update. ## Response `200` Result per item, in request order: the id of the created or updated record, or the error. - object - `success` boolean: True when the request succeeded; false on error. - `data` union[] - union - string, uuid: Id of the created or updated record. - Error: The body of every REST error. `code` and `name` are stable identifiers; `message` is for people. The full list of codes is at https://developers.coevera.com/reference/errors/. - `http_status` integer, required: HTTP status code. - `code` integer: Numeric code of the API error. - `name` string: Name of the API error. - `message` string: Message describing the error. - `success` boolean, required: Always false on error. ## Other responses - `400`: Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. - `401`: Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). - `422`: Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. - `429`: Too many requests (code 182). Wait for the seconds in Retry-After, then retry. - `500`: Unexpected server error (code 1000, ERROR_UNKNOWN). --- [API](https://skmtc.dev/coevera/apis/coevera-crm-api.md) - [All operations](https://skmtc.dev/coevera/apis/coevera-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coevera/apis/coevera-crm-api/revisions/40ebbc83f179?raw)