Specifications

URLs

The base URL for the API is: https://api.sama.com/v2

Authentication and security

To guarantee data security, you will only be allowed to connect to the Sama Platform API over SSL using URLs that begin with “https”. A unique API access key will be generated for every client account during the setup stage. All API requests require that you pass your API access key as a query string parameter of your request: https://api.sama.com/v2/<...>?access_key=<ACCESS_KEY>

Request data formats

For writing data in CREATE (HTTP POST) and UPDATE (HTTP PUT) operations, the Sama Platform API currently supports JSON formatted data and requires the Content-Type header to be set to application/json

Task input data formats

Sama Platform supports three data format types: strings, integers, and dates. These are configured by Sama Project Managers during project setup.

String - Allows any combination of numbers, symbols and characters. Long strings (up to 16MB) are permitted.
Integer - Allows any 32-bit integer. Negatives permitted.
Date - Allows dates in ISO-8601 format (YYYY-mm-dd). All other date formats (including DateTime format) will return an error.

Project setup

Each project will be set up by a Sama Project Manager. Project Managers will work closely with your team to design a customized interface and workflow on the Sama Platform.

During the project setup, our integration team will work with you to determine:

the format and schema for your tasks
an API access key for your system to make calls to ours
the creation callback URL and authentication credentials for task creation results (optional, not necessary if using sync task creation or batch task creation)
the format and schema for the completed responses
the delivery callback URL and authentication credentials for the delivered tasks (optional, not necessary if using pull delivery)

Integration steps

After the business requirements have been met with the project setup Sama Engineering will be available to address any technical questions and complete the integration. A project is considered ready for production after the following steps are complete.

Integration testing

Initial test calls are made to a clone of your production project in order to confirm:

task input schema by creating tasks and by verifying the creation JSON schema
creating tasks one at a time or in batches
creation callback URL and authentication by accepting a request from the Sama Platform (optional)
task output schema by polling tasks and by verifying the delivery JSON schema
delivery callback URL and format by accepting API call from the Sama Platform (optional)
polling delivery either since given date or recently delivered ones

Production server trial

Once the project creation and delivery schemas are verified a small batch of tasks are completed on the Sama Platform production environment.

approximately 50 tasks are posted to the Sama Platform production environment where they will be completed by workers
confirm delivery of tasks

At this point your project has been tested end to end on the production server and is ready for full production volumes.