COcoevera
Lead & Opportunity

Create or update leads in a batch

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.

post/entities/Leads/batch-modify

Request

Query parameters

validation-levelinteger

Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117.

rollback-method0 | 1

0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item.

Request body

createdstring date-time

Creation time.

currency_exchange_rates_list_idstring uuid

Id of the currency exchange rate list applied to this lead.

descriptionstring

Free-form description of the lead.

is_archivedboolean

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_flagstring

User-set colored flag used to highlight the lead in lists and reports.

last_ai_buying_center_appliedstring date-time

Time when an AI-suggested buying center was last applied to this lead.

lead_source_idstring uuid

Id of the lead source recording how the lead originated (e.g. Website, Referral, Trade Show).

lead_type_idstring uuid

Id of the lead type that classifies the lead and drives which form, fields and lead process apply.

namestring

Name of the entity and its default text representation.

owner_idstring uuid

Id of the lead owner.

quick_account_emailstring

Free-text company email captured at lead creation when no Account record has been linked yet.

quick_account_namestring

Free-text company name captured at lead creation when no Account record has been linked yet.

quick_account_phonestring

Free-text company phone captured at lead creation when no Account record has been linked yet.

quick_contact_namestring

Free-text contact name captured at lead creation when no Contact record has been linked yet.

quick_emailstring

Free-text contact email captured at lead creation when no Contact record has been linked yet.

quick_phonestring

Free-text contact phone captured at lead creation when no Contact record has been linked yet.

rankinginteger

Qualitative ranking score (1-10) the user assigns to indicate the strength of the lead.

reason_of_close_descriptionstring

Free-form note explaining why the lead was archived (lost). Captured alongside reason_of_close.

reason_of_close_idstring uuid

Id of the reason recorded when the lead is archived (lost), or empty when none was given.

share_mode0 | 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_idstring uuid

Id of the lead process step.

unit_idstring uuid

Id of the sales unit.

revisioninteger

Revision when entity was lastly changed.

lost_datestring 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.

idstring uuid

ID of object to update.

Example request

[
  {
    "created": "2019-01-01T00:00:00",
    "currency_exchange_rates_list_id": "01234567-abcd-dcba-ffff-000000000000",
    "description": "string",
    "last_ai_buying_center_applied": "2019-01-01T00:00:00",
    "lead_source_id": "01234567-abcd-dcba-ffff-000000000000",
    "lead_type_id": "01234567-abcd-dcba-ffff-000000000000",
    "name": "string",
    "owner_id": "01234567-abcd-dcba-ffff-000000000000",
    "quick_account_email": "string",
    "quick_account_name": "string",
    "quick_account_phone": "string",
    "quick_contact_name": "string",
    "quick_email": "string",
    "quick_phone": "string",
    "ranking": 1,
    "reason_of_close_description": "string",
    "reason_of_close_id": "01234567-abcd-dcba-ffff-000000000000",
    "step_id": "01234567-abcd-dcba-ffff-000000000000",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "revision": 1,
    "lost_date": "2019-01-01T00:00:00"
  }
]

Response

Result per item, in request order: the id of the created or updated record, or the error.

successboolean

True when the request succeeded; false on error.

Example response

{
  "success": true,
  "data": [
    {
      "http_status": 400,
      "code": 117,
      "name": "ERROR_PARAMETER_INVALID"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.