Create Submission
Introduction
This API is used to create a new submission for processing in the specified campaign.
| Method | Service | API Name | Service Type |
|---|---|---|---|
| POST | submissions | create → Explore | Synchronous |
URI: https://{baseUrl}/submissions/v1/create
Header Elements
The header must contain the elements needed to authenticate the request.
| Parameter | Description | Type | Required |
|---|---|---|---|
| authorization | This is where you will send your encoded JWT auth token you obtained from Get Auth Token. Must be in the form: Authorization: Bearer {auth-token-string} | String | Yes |
Request Elements
This API supports the following attributes in the request.
| Name | Description | Type | Required |
|---|---|---|---|
| submission | The submission data to submit. | JSON Object | Yes |
| images | The images previously uploaded through the Upload Service to associate with this submission. The image name(s) returned by the upload service must be used. Example: "images": ["4805787701057672986d2ad5d33df63f8dcd6219.PNG", "180838bdf3bf1da3405725be763540d6601144.jpg"] | JSON object | No |
Submission
The submission object contains the following attributes.
| Name | Description | Type | Required |
|---|---|---|---|
| originType | Submission origin. Allowed values: - ON-LINE - PAPERLESS For standard campaigns the value ON-LINE should be sent. Submissions will then follow the standard scan and upload process.For campaigns where Blackhawk Network has a POS or other integration used to provide submission data as part of a processing and validation process, the value PAPERLESS should be used. This is a less common use-case. | String | Yes |
| campaignCode | The campaign code the submission should be created in. It is important submissions are created in the correct campaign so the correct validations can be applied and so that the application will receive the correct reward. | String | Yes |
| firstName | First name. - Max. Length: 35 - Regex: ^[a-zA-Z ]{0,35}$ | String | Conditional. If company name is not provided then this field is required. |
| lastName | Last name. - Max. Length: 35 - Regex: ^[a-zA-Z ]{0,35}$ | String | Conditional. If company name is not provided then this field is required. |
| companyName | Company name - Max. Length: 50 - Regex: ^[a-zA-Z0-9 &']{0,50}$ | String | Conditional If first name and last name are not provided then company name is required. |
| address1 | First line of the address. - Max. Length: 64 - Regex: ^[0-9a-zA-Z \#.,\-'\/]{0,64}$ | String | Yes |
| address2 | Second line of the address. - Max. Length: 64 - Regex: ^[0-9a-zA-Z \#.,\-'\/]{0,64}$ | String | No |
| city | City of the address. - Max. Length: 50 - Regex: ^[a-zA-Z ]{0,50}$ | String | Yes |
| stateCode | Two digit state code for the address. Example: TX. - Max. Length: 5 - Regex: ^[a-zA-Z]{2,5}$ | String | Yes |
| countryCode | Two digit ISO-3166 country code for the address. Only US and CA are allowed through this API.- Max. Length: 2 - Regex: ^US|CA$ | String | Yes |
| postalCode | ZIP Code or Postal Code of the address. Example: 75067 or A1A 1A1- Max. Length: 5 digits or 7 characters - Regex: ^\d{5}$|^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1}$ | String | Yes |
| zipPlus4Code | ZIP Code +4 value for the address (US only). - Max. Length: 4 - Regex: ^\d{4,4}$ | String | No |
| Email address. - Max. Length: 50 - Regex: ^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\.[a-zA-Z]{2,4}$ | String | No | |
| telephoneNumber | Telephone number. - Max. Length: 10 - Regex: ^[0-9]{0,10}$ | String | No |
| attributes | Campaign attribute values to be associated with the submission. Sent as key/value pairs. | List | Yes |
| products | Products to associate with this submission. | List | No |
| context | Client context to be used when creating the submission. This value will be provided to you during onboarding/integration. | String | Yes |
Products
| Name | Description | Type | Required |
|---|---|---|---|
| name | Product Name | String | Yes |
| attributes | Map of Product Attributes keyed by Product Attribute Name . | List | Yes |
Attributes
| Name | Description | Type | Required |
|---|---|---|---|
| name | Attribute Name. Must match name of the attribute configured by Blackhawk Network. | String | Yes |
| type | One of: - TEXT - INTLTEXT - NUMBER - DATE - TIME - BOOLEAN - FLOAT - CURRENCY - CHOICE - ENCRYPTED | String | Yes |
| value | Value of the attribute. See Field Mapping Formats Reference | String | Yes |
Sample Request
{
"submission": {
"originType": "ON-LINE",
"campaignCode": "32-12345",
"firstName": "Ronald",
"lastName": "Mallard",
"companyName": "",
"address1": "700 State Highway 121 Bypass Ste. 200",
"address2": "",
"city": "Lewisville",
"stateCode": "TX",
"countryCode": "US",
"zipPlus4Code": "",
"postalCode": "75067",
"email": "[email protected]",
"telephoneNumber": "9725550100",
"attributes": [{
"name": "Postmark Date",
"value": "04-18-2018",
"type": "DATE"
}, {
"name": "Store Number",
"value": "04567",
"type": "NUMBER"
}, {
"name": "Eligible Retailer",
"value": "false",
"type": "BOOLEAN"
}, {
"name": "Reward Type",
"value": "GC",
"type": "TEXT"
}
],
"products": [{
"name": "Generic Product",
"attributes": [{
"name": "Invoice Number",
"value": "12345",
"type": "TEXT"
}, {
"name": "Part Number",
"value": "565656",
"type": "TEXT"
}, {
"name": "Model Number",
"value": "565656",
"type": "TEXT"
}, {
"name": "Price",
"value": "10.00",
"type": "CURRENCY"
}, {
"name": "Quantity",
"value": "2",
"type": "NUMBER"
}, {
"name": "Transaction Date",
"value": "04-18-2018",
"type": "DATE"
}, {
"name": "Eligible Product",
"value": "true",
"type": "BOOLEAN"
}
]
}
]
},
"images": ["4805787701057672986d2ad5d33df63f8dcd6219.PNG"],
"context": "PARKANDCOMPANY"
}
Response
Upon success the service will respond with an HTTP status code 200 and provide a JSON response containing the following attributes.
| Name | Description | Type | Required |
|---|---|---|---|
| timestamp | Timestamp when the request completed processing. | Integer | Yes |
| status | Status of the response. This will match the HTTP Status Code in the header of the response. Example: 404 | String | Yes |
| error | If the request was not processed successfully this will indicate the error condition encountered. Example: "Not Found" | String | Yes (if status is ERROR) |
| message | The detailed error message. This will be null if the request completed successfully.Example: "Campaign Code 32-99999 could not be found" | String | Yes (if status is ERROR) |
| path | The path called in the request excluding the baseUrl. | String | Yes |
| trackingNumber | Submission tracking number. Example: 1234567890 | String | Yes (if status is SUCCESS) |
Sample Responses
{
"status": 201,
"error": null,
"message": null,
"path": "/submissions/v1/create",
"timestamp": 1585678495913,
"trackingNumber": "916468460"
}
{
"status": 400,
"error": "Bad Request",
"message": "Date of Birth:invalid",
"path": "/submissions/v1/create",
"timestamp": 1585678459127,
"trackingNumber": null
}
{
"status": 500,
"error": "Internal Server Error",
"message": "An unexpected exception occurred in the core submission service.",
"path": "/submissions/v1/create",
"timestamp": 1585678427076,
"trackingNumber": null
}
Error Handling - Best Practice Recommendation
If you receive an error when trying to create a submission, we recommend waiting 20 minutes before attempting the request again. If you continue to receive an error after three attempts please reach out to your account manager for further assistance.
Updated over 3 years ago