Submissions

Submissions are collections of records that are submitted against a campaign. The records are made up of the required recipient information and the relevant campaign specific fields that have been configured in the ZAP APP The POST endpoints allow users to submit either an entire self contained collection of records intended to be sent together on a specific date or they can submit individual records after an appropriate event has occurred.

For more information visit the documentation

POST/api/v1/records

Body

application/json

campaignId*string (uuid)

onlyValidRecordsboolean

scheduledSendId*nullable string (uuid)

submissions*nullable array of object

Response

200400401404

Success

Body

application/json

Other propertiesany

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/records', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "campaignId": "a514d72f-b5ff-41dd-85db-9fdaa2f8071d",
      "scheduledSendDateId": "19b9cbf8-319d-48e4-b80c-574221e43a39",
      "onlyValidRecords": true,
      "submissions": [
        {
          "customerid": "Value",
          "email": "Value",
          "salutation": "Value",
          "firstname": "Value",
          "surname": "Value",
          "address1": "Value",
          "address2": "Value",
          "address3": "Value",
          "city": "Value",
          "postcode": "Value",
          "country": "Value",
          "currency": "Value",
          "language": "Value",
          "customData": {
            "customField1": "Value",
            "customField2": "Value"
          }
        }
      ]
    }),
});
const data = await response.json();

A common use case for the records endpoint would be to submit an individual record when a basket is abandoned for an e-com journey or for a customer quote request

Record Batching

Its very important to note that low volumes of records submitted to the ZAPI will be compiled into larger submissions at the end of each day. This is to reduce the total volume of submissions created against a campaign and make monitoring a much easier task for regularly scheduled campaigns. This means you won't be able to query for any updates on records submitted until the day after submission when they've been batched.

For more information visit the documentation

POST/api/v1/submissions

Body

application/json

campaignId*string (uuid)

clientIdstring (uuid)

onlyValidRecordsboolean

scheduledSendId*nullable string (uuid)

submissions*nullable array of object

Response

200400401404

Success

Body

application/json

validatedSubmissionsnullable array of object

responseMessagenullable string

submissionIdnullable string (uuid)

invalidSubmissionsnullable array of object

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/submissions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "campaignId": "e5953489-20b8-48d4-a6b3-62b7a077ce5d",
      "scheduledSendDateId": "f346d162-945c-4d73-ace9-4d4d69ee01a2",
      "onlyValidRecords": true,
      "submissions": [
        {
          "customerid": "Value",
          "email": "Value",
          "salutation": "Value",
          "firstname": "Value",
          "surname": "Value",
          "address1": "Value",
          "address2": "Value",
          "address3": "Value",
          "city": "Value",
          "postcode": "Value",
          "country": "Value",
          "currency": "Value",
          "language": "Value",
          "customData": {
            "customField1": "Value",
            "customField2": "Value"
          }
        }
      ]
    }),
});
const data = await response.json();

Response

200

{
  "validatedSubmissions": [],
  "responseMessage": "text",
  "submissionId": "123e4567-e89b-12d3-a456-426614174000",
  "invalidSubmissions": []
}

A common use case for this endpoint would be when adding a collection of related records such as a group of renewal reminders for a monthly send or a list of lapsed customers

Users can also list any submissions that exist against a campaign or list submissions actively working through the ZAP flow before being sent.

GET/api/v1/Submissions/{campaignId}

Path parameters

campaignId*string (uuid)

Response

200400401404

Success

Body

application/json

campaignIdstring (uuid)

submissionIdstring (uuid)

submissionDateUTCstring (date-time)

scheduledSendDateUTCstring (date-time)

statusnullable string

recordsCountinteger (int32)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/Submissions/{campaignId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "submissionId": "123e4567-e89b-12d3-a456-426614174000",
    "submissionDateUTC": "2024-11-21T06:41:33.566Z",
    "scheduledSendDateUTC": "2024-11-21T06:41:33.566Z",
    "status": "text"
  }
]

GET/api/v1/Submissions/Active/{campaignId}

Path parameters

campaignId*string (uuid)

Response

200400401404

Success

Body

application/json

campaignIdstring (uuid)

submissionIdstring (uuid)

submissionDateUTCstring (date-time)

scheduledSendDateUTCstring (date-time)

statusnullable string

recordsCountinteger (int32)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/Submissions/Active/{campaignId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "submissionId": "123e4567-e89b-12d3-a456-426614174000",
    "submissionDateUTC": "2024-11-21T06:41:33.566Z",
    "scheduledSendDateUTC": "2024-11-21T06:41:33.566Z",
    "status": "text"
  }
]

Useful information

Scheduled Send Date selection

Any records or submissions sent to the ZAP API will be automatically included on the soonest available scheduled send if one is not specified. Unless you wish to use a specific send in the future it's most likely you don't need to specify the scheduled send on the request.

The OnlyValidRecords property

When creating a submission users have the option to set 'OnlyValidRecords' to true or false. When true the records in the submission will only be accepted if every record is valid. If 'OnlyValidRecords' is set to false, then any records that pass validation will be accepted and any that fail will not and will be returned in the usual response format detailing the validation failures.

Expected Values

Expected values are configured against fields on the campaign. If any expected values exist, then the API will only accept the values within that list. For example, I might configure a DayOfTheWeek field on my campaign. If I do this I may configure the expected values "Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" and "Sunday". Any records that fail because of an expected value will have the list of valid values returned in the error provided on submission.

Validation Expressions

Validations are regex expressions and paired messages. When a record is received against the campaign ZAP will validate that all validation expressions are passed. If any fail, a list of errors will be compiled with the relevant message configured for the validation expression. This piece of functionality provides more advanced validation as the regex expressions can get quite complex.

Custom Data

The custom data object is used for custom fields that are created for a campaign. Each customField property should match the 'label' given to the matching custom field. Querying the GET campaign/{CampaignId} endpoint will return a list of all custom fields for the campaign.

Default Field Validation

Property	Mandatory	ErrorMessage	Max Text Length
CustomerId	Yes	Must be unique	100
Email	No	be in standard email address format.	255
Salutation	No	Must be alphanumeric, full-stop and space only.	35
Firstname	Yes	Must be alphanumeric, space, -, (, ), full-stop and ' only.	35
Surname	Yes	Must be alphanumeric, space, -, (, ), full-stop and ' only.	35
Address1	Yes	Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.	35
Address2	No	Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.	35
Address3	No	Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.	35
City	No	Must contain alphanumeric, space, ', ., &, -, /, \ and , characters only.	255
Postcode	Yes	Must be alphanumeric, - and spaces only.	15
Country	Yes	Must contain letters, space, -, (, ), full-stop, & and ' only.	255
Currency	No	Must contain letters only.	3
Language	No	Must contain letters only.	10