Signpost API (2.1.0)

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

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.

Authentication

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.

HTTP-Basic-Auth

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

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:

    List Locations

    Returns a list of the locations of your business, with relevant information about each location.

    Authorizations:

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Contact

    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.

    Authorizations:
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    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"

    Responses

    Request samples

    Content type
    application/json
    {
    • "emails":
      [
      ],
    • "phones":
      [
      ],
    • "unparsedName": "John Doe",
    • "lifecycleStage": "ACTIVE"
    }

    Response samples

    Content type
    application/json
    {
    • "success": true
    }

    Bulk Create Contacts

    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.

    Authorizations:
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    Array ()
    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"

    Responses

    Request samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    {
    • "success": true
    }

    Unsubscribe Contact

    Unsubscribes the specified contact in the given location. A contact can be specified by a phone number or an email address.

    Authorizations:
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    email
    string
    phone
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "jdoe@email.com"
    }

    Response samples

    Content type
    application/json
    {
    • "success": true
    }

    Create Transaction

    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.

    Authorizations:
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    email
    string
    phone
    string
    unparsedName
    string non-empty
    firstName
    string non-empty
    lastName
    string non-empty
    amount
    required
    number
    timestamp
    required
    string <date-time>

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "jdoe@email.com",
    • "phone": "5556667777",
    • "firstName": "John",
    • "lastName": "Doe",
    • "timestamp": "2020-01-14T14:00:00.000Z",
    • "amount": 15.95
    }

    Response samples

    Content type
    application/json
    {
    • "success": true
    }

    Create Appointment

    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.

    Authorizations:
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    email
    string
    phone
    string
    unparsedName