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.

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.

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

post

For more information visit the documentation

Authorizations

AuthorizationstringRequired

Body

campaignIdstring · uuidRequired

onlyValidRecordsbooleanOptional

scheduledSendIdstring · uuid · nullableRequired

testModebooleanOptional

Responses

200

Success

application/json

responseMessagestring · nullableOptional

submissionIdstring · uuid · nullableOptional

401

Unauthorized

404

Not Found

500

Server Error

post/api/v1/records

POST /api/v1/records HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 498

{
  "campaignId": "770a1e90-d344-4467-a79d-255c01ca1298",
  "scheduledSendDateId": "1e6a1b00-7752-4631-9f9b-f731c7a35be9",
  "onlyValidRecords": true,
  "testMode": true,
  "submissions": [
    {
      "customerid": "Value",
      "email": "Value",
      "salutation": "Value",
      "firstname": "Value",
      "surname": "Value",
      "companyname": "Value",
      "address1": "Value",
      "address2": "Value",
      "address3": "Value",
      "city": "Value",
      "postcode": "Value",
      "country": "Value",
      "currency": "Value",
      "language": "Value",
      "customdata": {
        "customField1": "Value",
        "customField2": "Value"
      }
    }
  ]
}

{
  "validRecords": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "invalidRecords": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "duplicateIgnoredRecords": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "responseMessage": "text",
  "submissionId": "123e4567-e89b-12d3-a456-426614174000"
}

A common use case for the Submissions 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

post

For more information visit the documentation

Authorizations

AuthorizationstringRequired

Body

campaignIdstring · uuidRequired

onlyValidRecordsbooleanOptional

scheduledSendIdstring · uuid · nullableOptional

testModebooleanOptional

Responses

200

Success

application/json

responseCodeinteger · int32Optional

responseMessagestring · nullableOptional

submissionIdstring · uuid · nullableOptional

400

Bad Request

401

Unauthorized

404

Not Found

post/api/v1/submissions

POST /api/v1/submissions HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 498

{
  "campaignId": "08f8b771-1587-4e20-9de2-6441e35e5dea",
  "scheduledSendDateId": "b44eb900-dbd3-406f-b0d3-053175b9fc6c",
  "onlyValidRecords": true,
  "testMode": true,
  "submissions": [
    {
      "customerid": "Value",
      "email": "Value",
      "salutation": "Value",
      "firstname": "Value",
      "surname": "Value",
      "companyname": "Value",
      "address1": "Value",
      "address2": "Value",
      "address3": "Value",
      "city": "Value",
      "postcode": "Value",
      "country": "Value",
      "currency": "Value",
      "language": "Value",
      "customdata": {
        "customField1": "Value",
        "customField2": "Value"
      }
    }
  ]
}

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

Useful information

Test Mode

Test model enables you to create submissions in our production environment to test your API requests. These submissions will be created in the ZAP APP as if they were a normal submission so you can check that everything works however these submissions will not be included in any real mail sends and you will not incur any submission / ZAP credit costs. To use test mode set the testMode property to true when sending the request.

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.

Records endpoint duplicate customer ids within separate submissions:

We now support people submitting the same customer id more than once over separate requests to the "/records" endpoint. As a submission will only allow a single customer id, we will retain the data for the first record with that customer id and return a new "duplicateIgnoredRecords" object on any following requests that lists any records from the current submission that have not been accepted due to duplicates.

Default Field Validation

Property

Mandatory

ErrorMessage

Max Text Length

CustomerId

Yes

Must be unique

100

be in standard email address format.

255

Company Name

No*

Must be alphanumeric, space, -, (, ), full-stop and ' only.

120 total**

Salutation

No*

Must be alphanumeric, full-stop and space only.

120 total**

Firstname

No*

Must be alphanumeric, space, -, (, ), full-stop and ' only.

120 total**

Surname

No*

Must be alphanumeric, space, -, (, ), full-stop and ' only.

120 total**

Address1

No***

Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.

150 total****

Address2

No***

Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.

150 total****

Address3

No***

Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only.

150 total****

City

No***

Must contain alphanumeric, space, ', ., &, -, /, \ and , characters only.

150 total****

Postcode

No***

Must be alphanumeric, - and spaces only.

150 total****

Country

Yes

Must contain letters, space, -, (, ), full-stop, & and ' only.

255

Currency

Must contain letters only.

Language

Must contain letters only.

* The delivery name cannot be null, some combination of Salutation, First Name, Surname and Company Name is required.

** Since the name can be comprised of multiple fields the 120 character maximum applies cumulatively across the following fields Salutation, First Name, Surname and Company name

*** We will allow you to submit any combination address fields however we do require an address to deliver to. Your submission can be made up or one of more of the following fields: Address1, Address2, Address3, City, Postcode. Since some of our clients don't usually hold customer addresses, their data isn't always standardised. This makes it easier to submit the data you do have and we'll do the clean up.

**** Since the name can be comprised of multiple fields the 150 character maximum applies cumulatively across the following fields: Address1, Address2, Address3, City, Postcode

PreviousScheduledSends NextRejectedRecords

Last updated 19 days ago

Was this helpful?