Download OpenAPI specification:Download
The Signpost API v2 is a RESTful ingress-only API, which allows you to record new customers and new interactions for your business.
There might be short a delay between creating customers and interactions here and the information appearing in your Merchant Center.
Your location ID will be used in the URL of most queries you make to the API v2. Your location ID can be found using the list locations endpoint below.
It can also be found in the URL that you use to access Signpost as the parameter after "/locations/". For example, if your URL was https://my.signpost.com/165000/locations/6080500/dashboard, your location ID would be 6080500.
All API calls must be authenticated with either HTTP Basic Auth or OAuth 2.0.
HTTP Basic Auth requires no setup and is recommended for Signpost users calling this API for their own Signpost accounts. It can also be used for quick prototyping while setting up OAuth 2.0.
OAuth 2.0 requires some setup and is recommended for third-party services calling this API on behalf of other Signpost accounts.
Supply a standard basic authentication header on all API calls, comprised of your email address and password.
Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word "Basic" followed by a space and a base64-encoded string, "username:password". For example, to authorize as demo / p@55w0rd the client would send the header:
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Note: Because base64 is easily decoded, basic authentication should only be used together with other security mechanisms such as HTTPS/SSL.
| Security Scheme Type | HTTP |
|---|---|
| HTTP Authorization Scheme | basic |
OAuth 2.0 allows a Signpost user to authorize you to access their account without exposing their password.
The Signpost API is fully compliant with the OAuth 2.0 specification and supports the Authorization Code flow. The Authorization Endpoint is https://my.signpost.com/oauth2/authorize and the Token Endpoint is https://connect.signpost.com/oauth2/token. Access tokens do not expire.
To setup OAuth 2.0 send an email to api@signpost.com with a display name that should be shown to users on the consent screen and one or more Redirection Endpoint URIs. Our API support team will respond with a Client ID and Client Secret.
| Security Scheme Type | OAuth2 |
|---|---|
| authorizationCode OAuth Flow | Authorization URL: https://my.signpost.com/oauth2/authorize Token URL: https://connect.signpost.com/oauth2/token Scopes: |
Returns a list of the locations of your business, with relevant information about each location.
[- {
- "locationId": 1234,
- "merchantId": 5678,
- "name": "Signpost",
- "email": "api@signpost.com",
- "phone": "5555551234",
- "address": {
- "street1": "275 7th Ave.",
- "street2": "Suite 1701",
- "city": "New York",
- "state": "NY",
- "zip": "10001"
}, - "publishAddress": true,
}
]Creates a new contact for the specified location. A contact can be created with one or more email addresses and phone numbers, and can include a name. At least one phone number or email address is required. A contact's name, if provided, can be either an unparsed name or both a first and a last name. If a contact with this information already exists, it will be updated with any new fields. Optionally, a lifecycle stage can be supplied for the contact. The lifecycle stage can be one of "ACTIVE", "PROSPECT", "UNHAPPY" or "INACTIVE". The lifecycle stage will only be used when creating a new contact, it will not update the lifecycle stage of an existing contact.
| locationId required | integer Example: 6080500 Your location's ID. |
| emails | Array of strings |
| phones | Array of strings |
| unparsedName | string non-empty |
| firstName | string non-empty |
| lastName | string non-empty |
| lifecycleStage | any Enum: "ACTIVE" "PROSPECT" "UNHAPPY" "INACTIVE" |
{- "emails": [
- "jdoe@email.com",
- "john.doe84@email.com"
], - "phones": [
- "5556667777"
], - "unparsedName": "John Doe",
- "lifecycleStage": "ACTIVE"
}{- "success": true
}Creates a batch of contacts for the specified location. Between 1 and 500 contacts can be provided per request. Each contact can be created with one or more email addresses and phone numbers, and can include a name. At least one phone number or email address is required. A contact's name, if provided, can be either an unparsed name or both a first and a last name. If a contact already exists, it will be updated with any new fields. Optionally, a lifecycle stage can be supplied for each contact. The lifecycle stage can be one of "ACTIVE", "PROSPECT", "UNHAPPY" or "INACTIVE". The lifecycle stage will only be used when creating a new contact, it will not update the lifecycle stage of an existing contact.
| locationId required | integer Example: 6080500 Your location's ID. |
| emails | Array of strings |
| phones | Array of strings |
| unparsedName | string non-empty |
| firstName | string non-empty |
| lastName | string non-empty |
| lifecycleStage | any Enum: "ACTIVE" "PROSPECT" "UNHAPPY" "INACTIVE" |
[- {
- "emails": [
- "jdoe@email.com",
- "john.doe84@email.com"
], - "phones": [
- "5556667777"
], - "unparsedName": "John Doe",
- "lifecycleStage": "ACTIVE"
}, - {
- "phones": [
- "7875556644"
], - "firstName": "Jane",
- "lastName": "Doe"
}
]{- "success": true
}Unsubscribes the specified contact in the given location. A contact can be specified by a phone number or an email address.
| locationId required | integer Example: 6080500 Your location's ID. |
string | |
| phone | string |
{- "email": "jdoe@email.com"
}{- "success": true
}Creates a new transaction record for the specified location and contact. A transaction requires a timestamp (in ISO 8601 format) and a sale amount (in USD). It also requires an email address or a phone number to identify the contact associated with the transaction. If the contact does not exist, this endpoint will create a new one with the provided contact information. The contact's name can be provided as either an unparsed name or both a first and a last name.
| locationId required | integer Example: 6080500 Your location's ID. |
string | |
| phone | string |
| unparsedName | string non-empty |
| firstName | string non-empty |
| lastName | string non-empty |
| amount required | number |
| timestamp required | string <date-time> |
{- "email": "jdoe@email.com",
- "phone": "5556667777",
- "firstName": "John",
- "lastName": "Doe",
- "timestamp": "2020-01-14T14:00:00.000Z",
- "amount": 15.95
}{- "success": true
}Creates a new appointment for the specified location and contact. An appointment requires a timestamp (in ISO 8601 format) and an email address or a phone number to identify the contact associated with the appointment. If the contact does not exist, this endpoint will create a new one with the provided contact information. The contact's name can be provided as either an unparsed name or both a first and a last name.
| locationId required | integer Example: 6080500 Your location's ID. |
string | |
| phone | string |
| unparsedName |