> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safely.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Screen DNA synthesis customers for sanctions, organization, affiliation and scientific record.

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](https://docs.safely.bio/policies.md): 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

1. `POST /v1/screenings` with the customer's details. The API returns `202` and
   a pending screening at once.
2. Get the result by polling `GET /v1/screenings/{id}` or by receiving a
   [webhook](https://docs.safely.bio/webhooks.md). A screening usually takes under two minutes.
3. Optionally, record what you decided with `POST /v1/screenings/{id}/decision`.

## Authentication

Send your API key as a Bearer token over HTTPS:

```bash theme={null}
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

```bash theme={null}
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](https://docs.safely.bio/policies.md) 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](https://www.iso.org/obp/ui/#search/code/) 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](https://docs.safely.bio/errors.md).

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.