--- title: "Create or update leads in a batch" method: POST path: "/entities/Leads/batch-modify" tags: ["Lead & Opportunity"] --- # Create or update leads in a batch `POST /entities/Leads/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/Leads/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 lead; an item without one creates a lead. By default one invalid item fails the whole call with HTTP 422. ## Query parameters - `validation-level` integer - `rollback-method` 0 | 1 ## Request body - BatchLeadInput[] - `created` string, date-time: Creation time. - `currency_exchange_rates_list_id` string, uuid: Id of the currency exchange rate list applied to this lead. - `description` string: Free-form description of the lead. - `is_archived` boolean: True when the lead has been archived (lost). Archived leads remain readable but are hidden from active lists and cannot be edited until reactivated. - `label_flag` string: User-set colored flag used to highlight the lead in lists and reports. - `last_ai_buying_center_applied` string, date-time: Time when an AI-suggested buying center was last applied to this lead. - `lead_source_id` string, uuid: Id of the lead source recording how the lead originated (e.g. Website, Referral, Trade Show). - `lead_type_id` string, uuid: Id of the lead type that classifies the lead and drives which form, fields and lead process apply. - `name` string: Name of the entity and its default text representation. - `owner_id` string, uuid: Id of the lead owner. - `quick_account_email` string: Free-text company email captured at lead creation when no Account record has been linked yet. - `quick_account_name` string: Free-text company name captured at lead creation when no Account record has been linked yet. - `quick_account_phone` string: Free-text company phone captured at lead creation when no Account record has been linked yet. - `quick_contact_name` string: Free-text contact name captured at lead creation when no Contact record has been linked yet. - `quick_email` string: Free-text contact email captured at lead creation when no Contact record has been linked yet. - `quick_phone` string: Free-text contact phone captured at lead creation when no Contact record has been linked yet. - `ranking` integer: Qualitative ranking score (1-10) the user assigns to indicate the strength of the lead. - `reason_of_close_description` string: Free-form note explaining why the lead was archived (lost). Captured alongside reason_of_close. - `reason_of_close_id` string, uuid: Id of the reason recorded when the lead is archived (lost), or empty when none was given. - `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 - `step_id` string, uuid: Id of the lead process step. - `unit_id` string, uuid: Id of the sales unit. - `revision` integer: Revision when entity was lastly changed. - `contact_relations` object[]: Contacts linked to this lead, including their roles and org-chart positions. - `id` string, uuid: Id of the related LeadOpptyContactRelation record. - `account_relations` object[]: Accounts linked to this lead, including the primary-account flag. - `id` string, uuid: Id of the related LeadOpptyAccountRelation record. - `sharing_units` object[]: Sales units that have been granted shared access to this lead. Editable only when share_mode allows unit sharing. - `id` string, uuid: Id of the related LeadOpptySharingSalesUnitRelation record. - `sharing_clients` object[]: Users that have been granted shared access to this lead. Editable only when share_mode allows user sharing. - `id` string, uuid: Id of the related LeadOpptySharingClientRelation record. - `documents` object[]: Documents linked to this lead. - `id` string, uuid: Id of the related CloudObjectRelation record. - `tags` object[]: Tag labels applied to this lead. - `id` string, uuid: Id of the related TagRelation record. - `static_profiles` object[]: Saved view profiles this lead currently matches. - `id` string, uuid: Id of the related ProfileRelation record. - `lost_date` string, date-time: Timestamp of when the lead was archived (lost). Setting it adjusts the underlying loss event; empty for leads that have not been archived. - `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)