Documentation Powered by ReDoc

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:
    HTTP-Basic-AuthOAuth-2.0

    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:
    HTTP-Basic-AuthOAuth-2.0
    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:
    HTTP-Basic-AuthOAuth-2.0
    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:
    HTTP-Basic-AuthOAuth-2.0
    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:
    HTTP-Basic-AuthOAuth-2.0
    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:
    HTTP-Basic-AuthOAuth-2.0
    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
    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+03:00"
    }

    Response samples

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

    Create Email Interaction

    Creates a new email interaction for the specified location and contact. An email interaction requires a timestamp (in ISO 8601 format), the contact's email address, and a type ("incoming" if the contact emailed your business, "outgoing" if your business emailed the contact). 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:
    HTTP-Basic-AuthOAuth-2.0
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    email
    required
    string
    unparsedName
    string non-empty
    firstName
    string non-empty
    lastName
    string non-empty
    timestamp
    required
    string <date-time>
    type
    required
    any
    Enum: "incoming" "outgoing"
    subject
    string

    Responses

    Request samples

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

    Response samples

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

    Create Phone Call Interaction

    Creates a new phone call interaction for the specified location and contact. A phone call interaction requires a timestamp (in ISO 8601 format), the contact's phone number, the duration of the phone call interaction, and a type ("incoming" if the contact called your business, "outgoing" if your business called the contact). 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:
    HTTP-Basic-AuthOAuth-2.0
    path Parameters
    locationId
    required
    integer
    Example: 6080500

    Your location's ID.

    Request Body schema: application/json
    phone
    required
    string
    unparsedName
    string non-empty
    firstName
    string non-empty
    lastName
    string non-empty
    timestamp
    required
    string <date-time>
    type
    required
    any
    Enum: "incoming" "outgoing"
    durationSec
    required
    number

    Responses

    Request samples

    Content type
    application/json
    {
    • "phone": "5556667777",
    • "firstName": "John",
    • "lastName": "Doe",
    • "timestamp": "2020-01-14T14:00:00.000Z",
    • "type": "incoming",
    • "durationSec": 87
    }

    Response samples

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

    Upsert Estimate

    Creates or updates an estimate for the specified location and contact. An estimate requires the contact's phone number or email address (or both), a unique estimate id, the label you would like displayed when viewing the estimate in your Signpost account, the amount of the estimate (in dollars), and the workflow stage the estimate is in ("DRAFT" if it has not been sent to the contact, "SENT" if it has been sent to the contact, "APPROVED" if the contact as agreed to the estimate, "DECLINED" if the contact has declined the estimate). 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. Optionally, a description for the estimate, a url directly to the estimate on an external website system of record, and a soft delete flag may be provided.

    Authorizations:
    HTTP-Basic-AuthOAuth-2.0
    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
    estimateId
    required
    string non-empty
    label
    required
    string non-empty
    amount
    required
    number
    description
    string non-empty
    url
    string non-empty
    workflowStage
    required
    any
    Enum: "DRAFT" "SENT" "APPROVED" "DECLINED"
    deleted
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "johndoe@email.com",
    • "phone": "5556667777",
    • "estimateId": "estimate #3",
    • "label": "Quickbooks Estimate #3",
    • "description": "Quickbooks Estimate #3 for roofing at 123 Main St",
    • "url": "https://qbo.intuit.com/app/estimate?txnId=3",
    • "firstName": "John",
    • "lastName": "Doe",
    • "workflowStage": "DRAFT",
    • "amount": 12500,
    • "deleted": false
    }

    Response samples

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

    Upsert Job

    Creates or updates a job for the specified location and contact. A job requires the contact's phone number or email address (or both), a unique job id, the label you would like displayed when viewing the job in your Signpost account, the amount of the job (in dollars), the planned or actual start date/time, the planned or actual end date/time, and the workflow stage the job is in ("SCHEDULED" if it has been scheduled but not yet started, "IN_PROGRESS" if work is current being done, "COMPLETED" if the job is finished, "CANCELED" if the job has been canceled). 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. Optionally, a description for the job, a url directly to the job on an external website system of record, and a soft delete flag may be provided.

    Authorizations:
    HTTP-Basic-AuthOAuth-2.0
    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
    jobId
    required
    string non-empty
    label
    required
    string non-empty
    amount
    required
    number
    description
    string non-empty
    url
    string non-empty
    workflowStage
    required
    any
    Enum: "SCHEDULED" "IN_PROGRESS" "COMPLETED" "CANCELED"
    startTimestamp
    required
    string <date-time>
    endTimestamp
    required
    string <date-time>
    deleted
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "johndoe@email.com",
    • "phone": "5556667777",
    • "jobId": "job #3",
    • "label": "Quickbooks Job #3",
    • "description": "Quickbooks Job #3 for roofing at 123 Main St",
    • "url": "https://qbo.intuit.com/app/job?txnId=3",
    • "firstName": "John",
    • "lastName": "Doe",
    • "workflowStage": "SCHEDULED",
    • "amount": 12500,
    • "startTimestamp": "2020-10-04T08:00:00.000Z",
    • "endTimestamp": "2020-10-13T17:00:00.000Z",
    • "deleted": false
    }

    Response samples

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