Introduction - safely.bio Customer Screening API

The Customer Screening API checks a customer: sanctions and country restrictions, whether their organization is real and works in the life sciences, whether they work there, and whether they are a scientist. It returns a recommendation, a result for each area and a short summary you can store on the customer’s account. You choose what runs by naming a policy: for example, a basic screen at account creation, or a fuller screen with address checks before you ship. The API recommends; you decide. It never blocks an account or order. This version takes customer details only, with no order or sequence data.

How it works

POST /v1/screenings with the customer’s details. The API returns 202 and a pending screening at once.
Get the result by polling GET /v1/screenings/{id} or by receiving a webhook. A screening usually takes under two minutes.
Optionally, record what you decided with POST /v1/screenings/{id}/decision.

Authentication

Send your API key as a Bearer token over HTTPS:

Authorization: Bearer sb_live_...

You get separate test and live keys. Keys starting sb_test_ create test screenings, which live keys cannot read. Keep keys secret; ask us to revoke one at any time.

Quickstart

curl https://api.safely.bio/v1/screenings \
  -H "Authorization: Bearer $SAFELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_key": "acct-0061x00000AbCdE-1",
    "reference": "0061x00000AbCdE",
    "policy": "basic-onboarding",
    "customer": {
      "name": "Jane Smith",
      "email": "jane.smith@example.edu",
      "organization": "Example University",
      "group": "Smith Lab, Department of Microbiology",
      "country": "US"
    }
  }'

Field	Required	Meaning
`request_key`	Yes	Your unique key for this request, up to 200 characters. Retrying with the same key and body returns the same screening.
`reference`	No	Your own record ID, such as a Salesforce account ID. It comes back unchanged.
`policy`	Yes	The screening policy to apply, such as `basic-onboarding`.
`customer.name`	Yes	The person’s full name.
`customer.email`	Yes	The person’s email address.
`customer.organization`	Yes	The organization the person says they work for.
`customer.group`	No	Lab, group or department.
`customer.country`	Yes	Two-letter ISO 3166-1 alpha-2 country code, such as `US` or `GB`.
`customer.orcid`	No	ORCID iD. It helps match the person’s publications.
`customer.billing_address`, `customer.shipping_address`	No	Postal addresses, with `line1`, `line2`, `city`, `region`, `postal_code` and `country`. Policies with address checks use them.

The API rejects unknown fields, so a misspelled field fails instead of being ignored. Requests are limited to 64 KB. Each account has a limit on requests per minute and on new screenings per day, agreed when we set up your account. Over a limit, the API returns 429 with a Retry-After header; see errors. The response is 202 Accepted with a Location header. Poll that address until status is completed or failed, waiting the number of seconds in the Retry-After header between requests. A retry with the same request_key and body returns 200 and the saved screening.

Test keys

A test key runs a real screening, so use made-up customers. To test your integration without running checks, add test_scenario to the request:

`test_scenario`	Result
`approve`, `review`, `deny`	A completed screening with that recommendation.
`slow`	Stays `pending` for 60 seconds, then completes.
`failed`	A failed screening.
`unknown_values`	A recommendation and category result your code does not know, to test that it treats them safely.

These fixed screenings are kept briefly and can disappear when the service restarts. Live keys reject test_scenario.

​How it works

​Authentication

​Quickstart

​Test keys

How it works

Authentication

Quickstart

Test keys