Create a prospect

Operation ID: createProspect

Group: CRM › Prospects

Open in the interactive reference

POST /crm/prospects

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

Creates a prospect with its bill-to and sold-to addresses and its contacts, applying the rules of the prospect form in the app. Both addresses need line1, city, country and zipCode. Set sameAsBillToAddress to true and omit soldToAddress to use the bill-to address for both. A contact is either a new one, with displayName and emailAddress, or an existing contact linked by its id and nothing else; a contact can belong to one prospect only. At most one contact may be the default bill-to contact, and at most one the default sold-to contact. The response contains only the id; read the stored prospect, including its prospectNumber, 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: createProspectInput.

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

Response

200 Success

Under data (createProspectOutput):

Field Type Required Description
id string yes The unique identifier for the created prospect. Example: "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45". 
{
  "data": {
    "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
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