Physical Post

Endpoints for sending physical letters and postcards in the post

Send letters

Queues one or more letters for sending on behalf of the practice

Securityapi_key or azure_auth

Request

path Parameters

SiteSlug

required

string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$

The Slipstream slug that uniquely identifies a physical practice

Example: s8n6EzC

Request Body schema: application/json
required

The details of the letter to send

Array

Express	boolean or null Whether the letter should be sent by express delivery. If omitted, the default is standard delivery.
DoubleSided	boolean or null Whether the letter should be single or double sided. If omitted, the default is single sided.
Color	boolean or null Whether the letter should be printed in color. If omitted, the default is black and white.
PmsSpecificId required	string The unique ID of the letter in the pms system
ScheduledSendDate	string <date-time> The date to send the letter - omit or blank to send immediately
required	object or null (Addressee) The name and identity of a person
required	object (StreetAddress) Information about a street address.
required	object (DataUri) A URI that can be used to request data (usually files) from the PMS with a GET request. Typical implementations would be: azure storage SAS tokens S3 pre-signed URLs Google Cloud Storage signed URLs An endpoint on your app which accepts a GET request on the supplied URL and returns the data. Bonus points if HEAD returns a Content-MD5 header
SkipAddressValidation	boolean or null Whether to skip address validation of the recipient address
property name* additional property	any

Responses

202

The response of the physical letter sending request

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

409

ProblemDetails

412

ProblemDetails

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

post/sites/{SiteSlug}/physicalpost/letter

Request samples

Payload
curl
Ruby
C#
Node.js

application/json

[{"Express": false,
"DoubleSided": false,
"Color": false,
"PmsSpecificId": "{064a5f0e-0b0e-4e1e-8e1e-0e0e0e0e0e0e}",
"ScheduledSendDate": "2023-10-24T14:30:15+02:00",
"Addressee": {"PmsSpecificId": "1234567890abcdef1234567890abcdef",
"GivenName": "John",
"MiddleName": "Danger Blanket",
"FamilyName": "Smith",
"FullName": "Dr John Smith III"
},
"Address": {"AddressLine1": "123 Main St",
"AddressLine2": "Apt 4",
"Locality": "San Francisco",
"Region": "CA",
"PostalCode": "94107",
"Country": "USA"
},
"Pdf": {"Id": "12345678-1234-1234-1234-1234567890ab",
"DataUri": "https://staticinternalfilessa.blob.core.windows.net/images/Slipstream_tree.pdf?sp=r&st=2024-01-31T22:40:26Z&se=2026-01-02T06:40:26Z&spr=https&sv=2022-11-02&sr=b&sig=lbt2HQSdD%2BFG6x5hJK%2Brk2yZhMcZLqhiUm0tsu8xZ7E%3D",
"Expiry": "2021-01-01T00:00:00Z",
"RequestHeaders": {"X-API-KEY": "1234567890abcdef1234567890abcdef",
"user-agent": "slipstream/1.0.0",
"x-practice-site": "dentallyuk34554"
}
},
"SkipAddressValidation": false
}
]

Response samples

application/json

{"Succeeded": [{"Id": "064a5f0e-0b0e-4e1e-8e1e-0e0e0e0e0e0e",
"PmsSpecificId": "064a5f0e-0b0e-4e1e-8e1e-0e0e0e0e0e0e",
"AddressValidationStatus": "Unknown",
"ProblemDetails": {"type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
"title": "Bad Request",
"status": 400,
"detail": "Missing required field 'address'",
"instance": "/api/v1/physical-post/letters",
"traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}
}
],
"Failed": [{"Id": "064a5f0e-0b0e-4e1e-8e1e-0e0e0e0e0e0e",
"PmsSpecificId": "064a5f0e-0b0e-4e1e-8e1e-0e0e0e0e0e0e",
"AddressValidationStatus": "Unknown",
"ProblemDetails": {"type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
"title": "Bad Request",
"status": 400,
"detail": "Missing required field 'address'",
"instance": "/api/v1/physical-post/letters",
"traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}
}
]
}

Get a paginated list of all letter details owned by a site

Gets a list of letters

Securityapi_key or azure_auth

Request

path Parameters

SiteSlug

required

string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$

The Slipstream slug that uniquely identifies a physical practice

Example: s8n6EzC

query Parameters

pageSize

integer <int32> [ 1 .. 250 ]

The page number to retrieve

Example: pageSize=50

nextPageToken

string

A token retrieved from a previous request, used to retrieve the next page of results

status

string (LetterStatus)

The status of the letters to retrieve - if not provided, all statuses will be returned

Enum Value	Description
Unknown	The status of the letter is unknown - Default value - use when filtering letters when status value is not important
Created	The letter has been created but has not yet been sent to the mail provider
Pending	Sent to the mail provider and awaiting status updates from the mail provider
TransientFailure	A transient failure occured when attempting to send to mail provider, will retry
InvalidAddress	The destination address supplied is invalid
Failed	An unrecoverable failure occured when attempting to send to mail provider
Printing	The letter is currently being printed by the mail provider
InTransit	The letter is currently in transit to the destination address
Completed	Sucessfully delvered to the destination address
Cancelled	The letter was cancelled before it was sent

dateFrom

string <date>

The date to retrieve letters from - if not provided, all letters will be returned

includeHistory

boolean

If true, the response will include the history of the letter

Example: includeHistory=false

Responses

200

The letter details for this site

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

409

ProblemDetails

412

ProblemDetails

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

get/sites/{SiteSlug}/physicalpost/letter

Request samples

curl
Ruby
C#
Node.js

Response samples

application/json

{"Items": [{"Express": false,
"DoubleSided": false,
"Color": false,
"LetterId": "string",
"RecordId": "string",
"PmsSpecificId": "string",
"Addressee": {"PmsSpecificId": "1234567890abcdef1234567890abcdef",
"GivenName": "John",
"MiddleName": "Danger Blanket",
"FamilyName": "Smith",
"FullName": "Dr John Smith III"
},
"Address": {"AddressLine1": "123 Main St",
"AddressLine2": "Apt 4",
"Locality": "San Francisco",
"Region": "CA",
"PostalCode": "94107",
"Country": "USA"
},
"Pdf": {"Id": "12345678-1234-1234-1234-1234567890ab",
"DataUri": "https://staticinternalfilessa.blob.core.windows.net/images/Slipstream_tree.pdf?sp=r&st=2024-01-31T22:40:26Z&se=2026-01-02T06:40:26Z&spr=https&sv=2022-11-02&sr=b&sig=lbt2HQSdD%2BFG6x5hJK%2Brk2yZhMcZLqhiUm0tsu8xZ7E%3D",
"Expiry": "2021-01-01T00:00:00Z",
"RequestHeaders": {"X-API-KEY": "1234567890abcdef1234567890abcdef",
"user-agent": "slipstream/1.0.0",
"x-practice-site": "dentallyuk34554"
}
},
"Created": "2024-10-24T14:30:15+02:00",
"ScheduledSendDate": "2024-10-24T14:30:15+02:00",
"Sent": "2024-10-24T14:30:15+02:00",
"State": "Sent",
"StateDetails": "The letter was sent to the postal provider",
"Description": "A4 Letter [BlackAndWhite, Standard Delivery, Sent]",
"History": [{"Timestamp": "2024-10-24T14:30:15+02:00",
"Description": "The letter was sent to the postal provider",
"Status": "Unknown"
}
]
}
],
"NextPageToken": "eyJ0eXAiOi"
}

Get the letter details of a specific letter

Get the details of a letter

Securityapi_key or azure_auth

Request

path Parameters

SiteSlug required	string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$ The Slipstream slug that uniquely identifies a physical practice Example: s8n6EzC
LetterId required	string <uuid> The unique identifier (GUID) of the letter in slipstream Example: 44088399-d916-4de5-9f0a-dca7b3d07df2

query Parameters

includeHistory

boolean

If true, the response will include the history of the letter

Example: includeHistory=false

Responses

200

The letter details

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

409

ProblemDetails

412

ProblemDetails

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

get/sites/{SiteSlug}/physicalpost/letter/{LetterId}

Request samples

curl
Ruby
C#
Node.js

Response samples

application/json

{"Express": false,
"DoubleSided": false,
"Color": false,
"LetterId": "string",
"RecordId": "string",
"PmsSpecificId": "string",
"Addressee": {"PmsSpecificId": "1234567890abcdef1234567890abcdef",
"GivenName": "John",
"MiddleName": "Danger Blanket",
"FamilyName": "Smith",
"FullName": "Dr John Smith III"
},
"Address": {"AddressLine1": "123 Main St",
"AddressLine2": "Apt 4",
"Locality": "San Francisco",
"Region": "CA",
"PostalCode": "94107",
"Country": "USA"
},
"Pdf": {"Id": "12345678-1234-1234-1234-1234567890ab",
"DataUri": "https://staticinternalfilessa.blob.core.windows.net/images/Slipstream_tree.pdf?sp=r&st=2024-01-31T22:40:26Z&se=2026-01-02T06:40:26Z&spr=https&sv=2022-11-02&sr=b&sig=lbt2HQSdD%2BFG6x5hJK%2Brk2yZhMcZLqhiUm0tsu8xZ7E%3D",
"Expiry": "2021-01-01T00:00:00Z",
"RequestHeaders": {"X-API-KEY": "1234567890abcdef1234567890abcdef",
"user-agent": "slipstream/1.0.0",
"x-practice-site": "dentallyuk34554"
}
},
"Created": "2024-10-24T14:30:15+02:00",
"ScheduledSendDate": "2024-10-24T14:30:15+02:00",
"Sent": "2024-10-24T14:30:15+02:00",
"State": "Sent",
"StateDetails": "The letter was sent to the postal provider",
"Description": "A4 Letter [BlackAndWhite, Standard Delivery, Sent]",
"History": [{"Timestamp": "2024-10-24T14:30:15+02:00",
"Description": "The letter was sent to the postal provider",
"Status": "Unknown"
}
]
}

➔ Next to Email

Physical Post

Send letters

path Parameters

Request Body schema: application/jsonrequired

Get a paginated list of all letter details owned by a site

path Parameters

query Parameters

Get the letter details of a specific letter

path Parameters

query Parameters

Request Body schema: application/json
required