ARRIVE REST API

You can use the ARRIVE REST API with the ARRIVE SDK to manage the lifecycle of trips.

This documentation describes common use cases such as:

Sign up for the Curbside Platform

To access the ARRIVE REST API, you must sign up for the Curbside Platform. It is also recommended that you read the Quick Start for iOS App or the Quick Start for Android App before integrating the ARRIVE REST API.

Create a Usage Token

Once you are logged in, you can create a usage token.

When you are ready to move your app into production, create a separate usage token for production by checking the Production checkbox when creating it.

Requests

The ARRIVE REST API accepts JSON in the HTTP request body. All requests are handled over HTTPS.

Some requests require an app-id. If you are sending requests to the ARRIVE REST API from arrive.example.com, you can create an App ID such as arrive.example.com

Requests must be sent to the https://api.curbside.com/plt/ad/2017-05-31/notify endpoint.

Authentication

Requests must be authenticated using a usage token passed in the Curbside-Usage-Token HTTP header.

The ARRIVE REST API does not currently support Cross-Origin Resource Sharing (CORS). Requests can be proxied through your web server as a workaround.

Responses

The success or failure of each HTTP request is shown in the status field of the HTTP response header, which contains standard HTTP status codes:

  • a 2xx code for success
  • a 4xx or 5xx code for failure

An example of a successful response:

{"tid":"hello123456","destinations":[],"estimates":[]}

An example of an error response:

{
    "status": 400,
    "message": "Bad Request",
    "details": {
        "error": "curbside.api.error/string-length-exceeds-max-limit-or-nil",
        "data": {
            "string-name": "tid",
            "string-value": "ffffffffffffffffffffffffffffffffffffff",
            "max-length": 36
        }
    }
}

Please contact us if you encounter any HTTP 500 failures.

Errors

The following list identifies the error codes that you might encounter while working with the ARRIVE REST API:

Code Description
ad-inconsistent-device-id Different device IDs are present in different parts of the request.
ad-invalid-tid-format The tracking identifier format is invalid.
ad-null-value-in-required-field Unexpected null value.
ad-start-track-at-invalid-site Site ID specified in start_track doesn't exist.
ad-start-track-with-track-token-already-terminated Can't start track because another trip using the same track_token has already been terminated.
ad-site-data-error Site data is invalid. Please contact developer support .
ad-too-many-destinations The maximum number of destinations for a single request was exceeded.
ad-trip-limit-exceeded The maximum number of trips for the trial account was exceeded.
ad-unknown-site-id No site corresponding to the given ID was found.
string-length-exceeds-max-limit-or-nil Provided string is not valid.

API Versions

The ARRIVE REST API is version-controlled to ensure backward compatibility. Any breaking change to the API will result in a new release date embedded in the request path, and existing APIs will be unaffected. If you believe you have encountered a regression in a released API, please contact us.

Common Use Cases

Starting a Trip

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify \
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "start_track": {"destinations": [{"site_csin": "mysite_433",
                                             "track_token":"DJF2339"}]}}'
Attribute Description
tid Customer Tracking Identifier (trackingIdentifier in SDKs).
app_id App ID identifying your server.
start track.destinations[].site csin Site ID associated with the trip to start.
start track.destinations[].track token The track token identifying the trip to start.

Cancelling or Completing a Trip

Cancelling trips through the ARRIVE REST API is necessary when the trip cannot be fulfilled. For example, in a retail scenario, a trip might need to be cancelled when an order is cancelled due to an out-of-stock event.

Note that if a notify request contains instructions to both cancel and complete a trip, the completion will have precedence.

Cancelling a Single Trip

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "cancel_track": {"destinations": [{"site_csin": "mysite_433",
                                             "track_token":"DJF2339"}]}}'
Attribute Description
tid Customer Tracking Identifier (trackingIdentifier in SDKs).
app_id App ID identifying your server.
cancel track.destinations[].site csin Site ID associated with the trip to cancel.
cancel track.destinations[].track token The track token identifying the trip to cancel.

Cancelling all Trips at a Site for a Single User

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "cancel_track": {"destinations": [{"site_csin": "mysite_433"}]}}'
Attribute Description
tid Customer Tracking Identifier (trackingIdentifier in SDKs).
app_id App ID identifying your server.
cancel track.destinations[].site csin Site ID of the site where trips are to be cancelled.

In other scenarios, you might want to mark trips as completed using the following APIs:

Completing a Single Trip

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "stop_track": {"destinations": [{"site_csin": "mysite_433",
                                           "track_token":"DJF2339"}]}}'
Attribute Description
tid Customer Tracking Identifier (trackingIdentifier in SDKs).
app_id App ID identifying your server.
stop track.destinations[].site csin Site ID associated with the trip to complete.
stop track.destinations[].track token The track token identifying the trip to complete.

Completing all Trips at a Site for a Single User

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify \
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "stop_track": {"destinations": [{"site_csin": "mysite_433"}]}}'
Attribute Description
tid Customer Tracking Identifier (trackingIdentifier in SDKs).
app_id App ID identifying your server.
stop track.destinations[].site csin Site ID of the site where trips are to be completed.

Confirming that a User Arrived

This functionality enables you to confirm that a given user arrived at a site. This confirmation is processed by your monitor app or the ARRIVE Console. This API is the same as calling the notifyMonitoringSessionUserOfArrivalAtSite method in the iOS ARRIVE SDK or in the Android ARRIVE SDK.

curl -XPOST https://api.curbside.com/plt/ad/2017-05-31/notify
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"tid": "user123",
          "app_id": "com.myapp",
          "locations": [{"lat":38.906081, "lng":-104.863520, "timestamp":"2017-09-29T22:12:54Z"}]
          "i_am_here": {"site_csin": "cvs_244"}}'
Attribute Description
tid The user trackingIdentifier.
app_id App ID identifying your server.
locations[] (Optional) User location, if available.
i am here.site_csin ID of the site where the user arrived.

Retrieving sites near a location

This endpoint is useful when you need to retrieve your sites locations for use in your mobile app. It supports paging if you have more than 25 sites, in which case you can use the from and size parameters.

The endpoint can also be used to return sites around a given latitude, longitude.

Request

curl -XGET -G "https://api.curbside.com/plt/ad/2017-05-31/sites"
     -H 'Curbside-Usage-Token: YOUR-USAGE-TOKEN' \
     -d lat=-87.88391 \
     -d lng=41.881 \
     -d radius=300
Attribute Description
from (Optional) Defaults to 0.
size (Optional) Maximum number of records to return.
lat Latitude coordinate around which to filter.
lng Longitude coordinate around which to filter.
radius Radius (distance), in meters, from the coordinate.

Response

{
  "ad_sites": [
    {
      "address": {
        "line_1": "47655 223rd Street",
        "line_2": "",
        "city": "Flandreau",
        "state": "SD",
        "zipcode": "57028",
        "country": "US"
      },
      "updated_at": "2017-10-31T20:27:41.161Z",
      "site_name": "223rd Street, Flandreau",
      "site_id": "test_123",
      "loc": {
        "type": "Point",
        "coordinates": [
          -96.678645,
          44.14648
        ]
      }
    }
  ]
}