File Drop Service

The File Drop Service lets you send a file to Supply Lens. Supply Lens keeps the file as source data for one of your Integrations, then converts it into a Document automatically, using that Integration's Configuration.

There's one endpoint with two request forms. Both use the same URL; the request's Content-Type header picks the form.

What you need

Your Supply Lens contact gives you these.

Supply Lens must also:

1. Enable the File Drop Service for the Integration type.
2. Install one Integration of that type in your organisation.
3. Enable that Integration.
4. Configure that Integration to convert each document type you send.

Addresses

All addresses are for production.

The Authentication Service publishes its configuration at https://id.supplylens.co.uk/.well-known/openid-configuration.

Step 1: get an access token

The File Drop Service only accepts an access token from the Supply Lens Authentication Service. Get one with the OAuth 2.0 client credentials grant.

Request: POST https://id.supplylens.co.uk/connect/token with the header Content-Type: application/x-www-form-urlencoded.

• Don't send scope. The token automatically gets every scope Supply Lens gave your client, including file_drop:write.
• URL-encode each value. A secret can contain +, /, = or &, and the request fails if these aren't encoded.
• Read access_token from the response.

curl -s https://id.supplylens.co.uk/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "client_secret=<client_secret>"

You can send the client ID and secret with HTTP Basic authentication instead. If you do, leave client_id and client_secret out of the body.

curl -s https://id.supplylens.co.uk/connect/token \
  -u "<client_id>:<client_secret>" \
  --data-urlencode "grant_type=client_credentials"

The token response

A correct request returns 200 OK:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "file_drop:write organisations:read"
}

Reuse the token until it expires; don't get a new one for each file. Get a new token when the File Drop Service returns 401 Unauthorized, or before expires_in runs out. A wrong client ID or secret returns 400 Bad Request with "error": "invalid_client".

What the token must contain

The token is a JSON Web Token (JWT). You don't need to read it, but if a request fails, check these claims.

Step 2: send a file

Endpoint: POST https://filedrop.supplylens.co.uk/{integrationTypeId}/{organisationId} with the header Authorization: Bearer <access_token>.

JSON form

Send the file as the request body, with Content-Type: application/json, and the other values in the query string. The body can be any JSON value (an object, an array or a single value) and is required: an empty body causes a validation error.

Supply Lens stores the JSON with indentation and the content type application/json. The formatting changes; the data doesn't. URL-encode each query value: a value containing &, #, + or a space otherwise changes the query string.

curl -si "https://filedrop.supplylens.co.uk/<integration_type_id>/<organisation_id>?type=order&reference=PO-10001&id=PO-10001" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  --data-binary @order.json

Multipart form

Send every value as a part of a multipart/form-data body. Let your HTTP client set the Content-Type header, because it must include the boundary.

Send one file per request. Values in the query string are ignored: the multipart form only reads form parts. Set the file part's content type correctly, because Supply Lens keeps it with the file.

curl -si "https://filedrop.supplylens.co.uk/<integration_type_id>/<organisation_id>" \
  -H "Authorization: Bearer <access_token>" \
  -F "type=order" \
  -F "reference=PO-10001" \
  -F "id=PO-10001" \
  -F "file=@PO-10001.csv;type=text/csv"

How id, reference and the file name are used

Duplicate rules:

1. If you send id, it's compared with the external IDs of files the same Integration received before, for the same document type.
2. The comparison covers all the Integration's files, including those received another way and those sent without id (whose external ID is their file name).
3. If the same external ID is found, the file is rejected with 400 Bad Request and isn't kept.
4. If you don't send id, there's no duplicate check: the file is kept and converted every time you send it.

Size limit

A request can be at most 1 MB (1,048,576 bytes). The limit covers the whole request body; for the multipart form that includes the boundaries and every part. Larger requests get 413 Request Entity Too Large.

Document type values

Send one of these in type, and only a type Supply Lens has configured your Integration for. Supply Lens tells you which types your Integration accepts. Values are case-sensitive and lowercase.

Responses

Success

An accepted file returns 201 Created, with a Location header giving the file's address in the Supply Lens app (https://app.supplylens.co.uk/org/<organisation_id>/data/source/<id>) and this body:

{
  "id": "6710c2f4a1b2c3d4e5f60789"
}

id is the Supply Lens identifier of the source data. Keep it, and give it to Supply Lens support if there's a problem with the file.

201 Created means Supply Lens has kept the file. It doesn't mean the conversion is complete or correct: users see the result of the conversion in the Supply Lens app.

Errors

A rejected request returns a problem body (application/problem+json), with the cause in detail:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The integration type does not support file drop"
}

Checklist for a failed request

1. You're using the production addresses.
2. The Authorization header is Bearer <access_token>, with one space.
3. The token hasn't expired (it's valid for expires_in seconds).
4. The token has the file_drop:write scope and your organisationId claim.
5. The organisationId in the URL matches the claim in the token.
6. integrationTypeId is the value Supply Lens gave you, in lowercase.
7. type is a lowercase value from the document type list.
8. JSON form: type and reference are in the query string, and the body is JSON.
9. Multipart form: type and file are form parts, and the file part has a file name.
10. The request is no larger than 1 MB.
11. You haven't sent the same id before.