API

David Klein

December 24, 2021 07:56

For detailed information about your school’s endpoints, see: https://{your school’s subdomain}.admin.12twenty.com/api/v2/documentation

Quick Tips and Guidelines

All methods must be called using HTTPS.
All requests must include a valid authentication token. See below for details on how to obtain a token.
For requests that fail validation, a status code in the 400 or 500 range will be returned.
All properties of type date/time are in the UTC time zone (both requests and responses)

How to Authenticate

Each request made to the API must include an API token that authenticates with the web service. To obtain a token, a request to the token generation endpoint must be made using your customer API key which is provided to you by our customer success team.

Sample cURL request for obtaining an API authentication token using your API key as a GET parameter:

curl https://{your school’s subdomain}.admin.12twenty.com/api/client/generateAuthenticationToken?key=api_key_here

Sending an Authenticated Request

Once you have successfully gotten a authentication token from the token generation endpoint, you may begin to make requests to the functional endpoints. Each request must include the token in the Authorization security header with a Bearer value. Authentication tokens have an expiration period of 24 hours.

Sample cURL request to GET a list of students in the 2018 graduation class:

curl https://{your school’s subdomain}.admin.12twenty.com/api/v2/students?year=2018 -H "Authorization: Bearer auth_token_here"

Response Status Codes and Content

POST

The expected HTTP response code is 201 (Created) if the request is successful. For some endpoints, the created object will be returned as part of the response content body in JSON format with the newly created Id field populated. All endpoints will return an object with the Id field populated. We recommend executing a GET request if you need to further process the created entity.
The service will expect a JSON payload. Ensure you specify a 'Content-Type' header of ‘application/json’.

PUT

The expected HTTP response code is 204 (No Content) or 200 (OK) if the request is successful. For some endpoints, the updated object may be returned as part of the response. We recommend executing a GET request if you need to further process the updated entity.
The service will expect a JSON payload. Ensure you specify a 'Content-Type' header of ‘application/json’.
- Suggestion: When updating an existing student user account, we recommend using a PATCH request. If you prefer to send a PUT request, it is highly recommended to first GET the student details, and then PUT any updates. Send all fields returned in the GET request to avoid clearing out existing data.

DELETE

The expected HTTP response code is 200 (OK) if the request is successful. No content will be returned.

GET

The expected HTTP response code is 200 (OK) if the request is successful.
Content will be in JSON format
Note the following when querying a list of results (e.g. /api/v2/students):
- Not all properties of an entity are returned when retrieving a list of entities. Query the individual entity’s endpoint to retrieve all properties available for the entity (e.g. /api/v2/students/12345)
- Page size defaults to 25
- Page size cannot be greater than 500

The below is a sample JSON response that contains a paged list of entities returned:

{
    "PageSize": 25,
    "PageNumber": 1,
    "Total": 277,
    "Items": [
        {
            "Id": 123,
            "Name": "Homer Simpson"
        }
    ]
}

Property Types

Property Type	Sample Value and Notes
Byte	2018
Byte[]	"YearIds": [2018, 2019, 2020]
Int16	187
Int16[]	"YearIds": [2018, 2019, 2020]
Int32	187
Int32[]	"PreferredIndustryIds": [1, 2, 3]
Int64	10607302981934
Int64[]	"PreferredIndustryIds": [1, 2, 3]
List	"PreferredIndustryIds": [1, 2, 3]
String	"sample string value"
Boolean	true
DateTime (UTC)	2020-05-20T18:25:43
Id Object	"YearsExperience": { "Id": 12345 }

Best Practices

Send requests one at a time to avoid exceeding the concurrent request limit
When pulling data out of 12Twenty to sync to another system, query only the entities that have recently changed by specifying the 'last modified date' in the query criteria
When updating data within 12Twenty, ensure you are only updating data that has actually changed. All updates are logged and viewable in the GUI; sending excessing PUT requests, for example, is not only inefficient, but also clutters the audit log and is confusing for career center admins to see API user updates where no changes are made.
Ideally run larger scale API processes during off-peak hours

API Usage Limits

12Twenty employs rate limiting to ensure that our API is utilized in an efficient manner and to ensure excessive API requests do not impact other users of the platform.

Connection Rate Limits / Throttling

Exceeding a rate limit will cause a 429 "Too many requests" error response and your app should respond by retrying with exponential backoff. 12Twenty employs a rate limit of 3 concurrent request per school and 5,000 requests per day.

We recommend that infrequent, larger scale data synchronization processes be performed over a number of days to help ensure you do not exceed the daily usage limit.

API