Bulk create prospects

Operation ID: bulkCreateProspects

Group: CRM › Prospects

Open in the interactive reference

POST /crm/prospects/bulk

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates multiple prospects in one request, up to 100. Each entry takes exactly the input of POST crm/prospects and is checked by the same rules. All-or-nothing: if any entry is invalid, the call fails with that entry's error, 'index' set to its zero-based position in prospects, and nothing is created. The response lists the new ids in input order; read a prospect with GET crm/prospects/:id.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: bulkCreateProspectsInput.

Field Type Required Description
prospects array<object> yes The prospects to create, at most 100. Each takes the input of POST crm/prospects. If any entry is invalid, nothing is created. Example: [{"prospectName":"Northwind Logistics","entityId":"a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88","sameAsBillToAddress":true,"billToAddress":{"line1":"410 Terry Avenue North","city":"Seattle","stateProvince":"US-WA","country":"US","zipCode":"98109"}},{"prospectName":"Contoso Freight","entityId":"a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88","sameAsBillToAddress":true,"billToAddress":{"line1":"1 Harbour Road","city":"Portland","stateProvince":"US-OR","country":"US","zipCode":"97201"}}].
prospects[].prospectName string yes The name of the prospect organization. Must not be empty.
prospects[].entityId string yes The legal entity that owns the prospect. See id on GET base/entities.
prospects[].billingEmail string no The email address invoices for this prospect would be sent to.
prospects[].crmId string no The identifier of this prospect in an external CRM system.
prospects[].customerType any no The commercial relationship. Defaults to 'default'. One of: "default", "partner".
prospects[].defaultCurrency string no The currency quotes for this prospect default to. Format ISO 4217, for example 'USD'.
prospects[].sameAsBillToAddress boolean no Whether the sold-to address repeats the bill-to address. When true, omit soldToAddress. Defaults to false.
prospects[].billToAddress object yes The prospect's bill-to address.
prospects[].billToAddress.line1 string yes The first address line: street number and name, or PO box. Must not be empty.
prospects[].billToAddress.line2 string no The second address line: apartment, suite, unit, building or floor.
prospects[].billToAddress.city string yes The city or locality. Must not be empty.
prospects[].billToAddress.stateProvince string no The state, province or region, as an ISO 3166-2 code of the country, for example 'US-WA'. Required when country is 'US'.
prospects[].billToAddress.country string yes The country, as an ISO 3166-1 alpha-2 code, for example 'US'.
prospects[].billToAddress.zipCode string yes The postal or ZIP code. Must not be empty.
prospects[].billToAddress.attention string no The person or department that mail to this address is for.
prospects[].soldToAddress object no The prospect's sold-to address. Required unless sameAsBillToAddress is true, and must be omitted when it is.
prospects[].soldToAddress.line1 string yes The first address line: street number and name, or PO box. Must not be empty.
prospects[].soldToAddress.line2 string no The second address line: apartment, suite, unit, building or floor.
prospects[].soldToAddress.city string yes The city or locality. Must not be empty.
prospects[].soldToAddress.stateProvince string no The state, province or region, as an ISO 3166-2 code of the country, for example 'US-WA'. Required when country is 'US'.
prospects[].soldToAddress.country string yes The country, as an ISO 3166-1 alpha-2 code, for example 'US'.
prospects[].soldToAddress.zipCode string yes The postal or ZIP code. Must not be empty.
prospects[].soldToAddress.attention string no The person or department that mail to this address is for.
prospects[].contacts array<object> no The prospect's contacts. Each is a new contact, or an existing one linked by id.
prospects[].contacts[].id string no An existing contact to link. It must not belong to another prospect. When set, send no other contact details.
prospects[].contacts[].displayName string no The contact's display name. Required for a new contact.
prospects[].contacts[].salutation string no The contact's form of address, for example 'Ms' or 'Dr'.
prospects[].contacts[].firstName string no The contact's given name.
prospects[].contacts[].middleName string no The contact's middle name or initial.
prospects[].contacts[].lastName string no The contact's family name.
prospects[].contacts[].suffix string no The contact's name suffix, for example 'Jr' or 'PhD'.
prospects[].contacts[].emailAddress string no The email address the contact is reached at. Required for a new contact.
prospects[].contacts[].workPhone string no The contact's work telephone number.
prospects[].contacts[].isDefaultBillToContact boolean no Whether this is the default contact for the bill-to address. Defaults to false.
prospects[].contacts[].isDefaultSoldToContact boolean no Whether this is the default contact for the sold-to address. Defaults to false. 
{
  "prospects": [
    {
      "prospectName": "Northwind Logistics",
      "entityId": "a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88",
      "sameAsBillToAddress": true,
      "billToAddress": {
        "line1": "410 Terry Avenue North",
        "city": "Seattle",
        "stateProvince": "US-WA",
        "country": "US",
        "zipCode": "98109"
      }
    },
    {
      "prospectName": "Contoso Freight",
      "entityId": "a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88",
      "sameAsBillToAddress": true,
      "billToAddress": {
        "line1": "1 Harbour Road",
        "city": "Portland",
        "stateProvince": "US-OR",
        "country": "US",
        "zipCode": "97201"
      }
    }
  ]
}

Response

200 Success

Under data (bulkCreateProspectsOutput):

Field Type Required Description
created array<object> yes The created prospects, in the same order as the input. Match rows to inputs by index. Example: [{"id":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"},{"id":"8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8"}].
created[].id string yes The unique identifier for a created prospect. 
{
  "data": {
    "created": [
      {
        "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"
      },
      {
        "id": "8c1f4a72-6b09-4d15-a3e7-40d2b6915cf8"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
TOO_MANY_PROSPECTS 400
ENTITY_NOT_FOUND 400
INVALID_PROSPECT_NAME 400
INVALID_BILLING_EMAIL 400
CURRENCY_NOT_FOUND 400
INVALID_ADDRESS 400
MISSING_SOLD_TO_ADDRESS 400
UNEXPECTED_SOLD_TO_ADDRESS 400
CONTACT_NOT_FOUND 400
INVALID_CONTACT 400
CONTACT_DETAILS_WITH_ID 400
DUPLICATE_CONTACT 400
CONTACT_ALREADY_LINKED 400
DUPLICATE_DEFAULT_CONTACT 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses