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.

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. The created object will be returned as part of the response content body in JSON format with the newly created Id field populated.

  • 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. The updated object will be returned as part of the response content body in JSON format.

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

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

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)

2016-05-20T18:25:43Z

DateTime

2016-05-20T18:25:43

Id Object

"YearsExperience": {
"Id": 12345
}

API Usage Limits

Connection Rate Limits / Throttling

Exceeding a rate limit will cause an HTTP 503 Server Too Busy response and your app should respond by retrying with exponential backoff. The current connection limit is 10 simultaneous connections per user account. If you hit that limit, we will be returning a normal error message. You'll have every opportunity to handle that gracefully in your applications. Note: currently there are no options to raise that limit on a per-customer basis.

Daily Usage Limits

Each customer has a limit of 5,000 API calls per day.