API

Quickstart

Before getting started with the API Quickstart, you're going to need a secret key. If you don't already have one contact sales@pinn.ai and we'll be in touch.

Overview

The Pinn API is a predicable and resource driven RESTful web service, all of our endpoints both accept and return well documented JSON objects. This guide will cover getting setup to hit the API and what to expect while interacting with our web services.

Authentication

Authenticating to the API is simple, provide your secret key in the Authorization header as a "Bearer" token. Your secret key gives you access to all your account information so be sure to keep it safe, never expose this key in client source code or make it publicly accessible. Using curl you can provide the header like so: -H "Authorization: Bearer sk_UARVMmt0UsoXTt3tef7GosibpBq3zh"

Try it out:

curl https://pinnapis.com/v1/users -H "Authorization: Bearer sk_UB8hITybDSwMBVSEBGYV8ZqYAaabHS5e"
        

If you successfully authenticated with the API you will receive a 200 OK response from the server, otherwise we will always return a 401 UNAUTHORIZED if a secret key was not provided or was invalid.

Errors

Our API returns errors as predictable JSON responses as well, it is important that your integration gracefully handles these different potential error cases. Here is the standard structure for all error responses:

{
    "error": {
        "code": "400",
        "type": "bad_request",
        "message": "Data received was not valid JSON"
    }
}
        
Key Description
code The HTTP status code of the response
type A specific error type, representing the condition of failure when code lacks specificity.
message A developer friendly error message, helpful for debugging programmatic errors

!

Note

Check out the API Reference for documentation on possible errors for each operation

Pagination

All resources have a top level list operation, e.g. GET https://pinnapis.com/users. Each one of these calls will produce paginated list results. Upon successful query, the data key will always contain an array of the requested resource.

Pinn has a cursor based pagination protocol, in order to fetch the next page of results simply provide a starting_after query parameter. You can easily get this from the "current" page by inspecting the top level ended_at key.

!

Note

If the results has a null value for ended_at or has_more is false no additional pages are able to be fetched.

Each page will yield the number of results specified by the limit query parameter, this value is capped at 100 entries per request. As the name suggests this is an upper bound on the number of results, so if less results than that exist we will just pass back the remainder.

Request IDs

Each request to the API will have an associated Request ID, this globally and uniquely identifies the request made (both failed and successful requests). If you need to contact us about a specific request, please provide the request ID to help us promptly resolve any issues.

You will find the ID in the HTTP response headers, under the key Request-Id like so:

HTTP/1.1 200 OK
Request-Id: req_PCoQRAALRpeG53guq2dnxxO8
        

Privacy

The Pinn API was built to be privacy conscious to your system's data, especially end user data. Our services are intentionally built to provide "pseudonymization".

GDPR regulations define pseudonymization as:

!

Note

“the processing of personal data in such a way that the data can no longer be attributed to a specific data subject without the use of additional information.”

Within the Pinn platform our services are context unaware. For example, when a user is created under your Pinn account we have no way of personally identifying who that user is. This puts the burden on your system to identify the user, which can be simply done by retaining the Pinn user_id alongside the user object in your data storage solution.

Critical API Operations

This section discusses certain API operations that are mandatory to implement, special care should be taken to read the full documentation regarding these touch points.

Operation Description
Create User Generates a new Pinn user, which provides a target for both enrollment and authentication. This is required before any enrollment or authentication integration can be done.
Create Enrollment Key Once a user is created, your backend must implement an endpoint to allow the user to obtain an enrollment key, which will allow the end user to enroll with Pinn. The logic on if a user is authorized to enroll is up to your implementation.

Quotas & Rate Limiting

In order to prevent abuse of the API, each account has a quota of 1,000,000 requests per month. This quota limit only applies to requests made to our API using your secret key, therefore it doesn't apply to actions like authentication. Should you need your quota raised please contact dev@pinn.ai and we can help raise your limit.

Our API provides information regarding your current usage via HTTP response headers. Here's a list of the headers we provide to track quota use.

Header Description
X-RateLimit-Limit Your total monthly limit, which by default is 1,000,000 requests per/month.
X-RateLimit-Remaining Number of requests still available for use
X-RateLimit-Reset A unix timestamp integer of the time when your quota is up for reset

In the event that your exceed your quota, your API client will receive the following error:

{
    "error": {
        "code": 429,
        "message": "This account has exceeded the set request limit, try again later.",
        "type": "rate_limit_error"
    }
}
        

?

Questions?

We are here to help! Contact us with any development related questions at dev@pinn.ai and we'll reach back in a timely manner.