Last Updated: October 22, 2023

Responsible Individual: Ben Saunders

<aside> 💡 Purpose: This document describes the API details for connecting to Signapse BSL Train Announcement Solutions.

Covered APIs:

• Authentication
• Create train announcement sign video request
• Train announcement request status </aside>

Authentication

Authentication is based on oauth2 specification and all the API endpoints are behind this authentication. So its necessary to authenticate with our servers first in order to gain access to the resources.

curl --location --request POST '<https://sign-stag.auth.eu-west-2.amazoncognito.com/>
oauth2/token' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--header 'Authorization: Basic {clientid&clientSecretBase64}' \\
--data-urlencode 'grant_type=client_credentials'

We will provide the clientid and clientsecret to generate the Basic value in the Authorization header.

This endpoint will return the below response with 200 status code. Access token here is a JWT token.

{
    "access_token": "jwttoken",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Create BSL Train Announcement Request

Use this API endpoint to make a BSL Train Announcement request.

curl --location '<https://sign.client.api.stag.signapsesolutions.com>
/v1/sign-requests/train-announcements' \\

--header 'Authorization: Bearer {token}' \\
--header 'Content-Type: application/json' \\
--data '{
    "destination": "HOB",
    "timing": "1210",
    "platform": "1", 
    "operator": "SE"
    "updatedTiming": "",
    "updatedPlatform": "",
    "shortDelay": false,
    "busReplacement": false,
    "cancelled": false,
    "noPlatform": false,
    "callingAt": "POO,BMH,WAT",
		"notCallingAt": "",
    "currentStation": "",
    "bgColour": "18,195,83",
    "metaData": {
        "messageId": "messageId here - record of the request id of the client system",
        "tenantId": "tenantId here - client which system",
        "userRequestingId": "userRequestingId here - person who made the request",
        "requestTime": "requestTime here - request time from the client side"
    }
}'

This endpoint will return the below response with 200 status code.

{
    "data": {
        "id": "c4c7ac45-79c2-48b2-99ff-61775e2d3d3e"
    }
}

id here is the request/job/submission id. Use this id to get the status of the request and link for the result output file.

NOTE: There is a request limit of 1,500 requests per 5 minutes on both Staging and Production.

Train announcement request status

Use this API endpoint to get the status of the sign request. ${requestId} is the id from the previous endpoint.

curl --location --request GET '<https://sign.client.api.stag.signapsesolutions.com/v1>
/sign-requests/${requestId}?filter=status' \\
--header 'Authorization: Bearer token'

This will return below response with status code 200

{
    "data": {
        "status": "IN_PROGRESS"
    }
}