API

Updated June 05, 2024 16:04

This article provides an overview of how to effectively use the 12Twenty API for managing school data. Detailed instructions on obtaining an API token, sending authenticated requests, and understanding response status codes are provided. The article also outlines best practices for API usage, including managing rate limits and ensuring efficient data synchronization.

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

Sections

Benefits of API Integration

Streamlined Data Management: Connecting your Student Information System (SIS) to 12twenty ensures seamless transfer and integration of student data, reducing the need for manual data entry and minimizing errors.
Enhanced Reporting and Analytics: Integrated systems allow for comprehensive data analysis and reporting, providing valuable insights into student outcomes, trends, and areas for improvement.
Improved Student Tracking: With real-time data synchronization, schools can effectively track student progress, from admissions through to graduation and beyond, enhancing support and engagement.
Efficient Resource Allocation: Access to up-to-date and accurate data helps institutions allocate resources more effectively, ensuring that support services are directed where they are most needed.
Better Career Services: Integration with 12twenty's career management platform enables students to seamlessly access job postings, career events, and employer connections, enhancing their employment prospects.
Compliance and Accreditation: Automated data integration assists in maintaining compliance with educational standards and accreditation requirements by ensuring accurate and timely data reporting.
User-Friendly Experience: A connected SIS and 12twenty system provide a more user-friendly experience for students, faculty, and administrative staff by consolidating data into a single, easily accessible platform.
Informed Decision-Making: Comprehensive and integrated data supports informed decision-making at all levels of the institution, from strategic planning to individual student interventions.

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.

Frequently Asked Questions

How do I find the attribute ID for a custom attribute?
To find the attribute ID for a custom attribute, you can go to https://{siteinstance}.admin.12twenty.com/api/v2/attributes and find the short or long display name by using CMD + F (Mac) or CTRL + F (PC).
How do I find API lookup keys?

You can use the URL https://{your school’s subdomain}.admin.12twenty.com/api/V2/lookups and use CMD + F (Mac) or CTRL +F (PC) to search the attribute you are looking for. For example, if you wanted to find the lookup ID for Work Authorization, you can use the find command and type in the attribute name. You will be able to find the attribute ID value:

Next, you can use this URL https://{your school’s subdomain}.admin.12twenty.com/api/V2/lookups/{ID}/options and insert the ID. For example, to find the Work Authorization options, you can use the URL https://{your school’s subdomain}.admin.12twenty.com/api/V2/lookups/285/options
I lost my API key, what can I do?
12twenty does not store API keys in a readable format once it is shared with your team. If an API key is active for your site, 12twenty can generate a new one, but any scripts or applications using the old key will need to be updated. Please note that 12twenty is unable to retrieve a key after it has been generated. If you need us to provide a new key, please reach out to support@12twenty.com and indicate which environment you need a new key for (Production or Sandbox)
What can I use to test the API before I make changes in our Production (Live) site?
You can use the sandbox environment to test the API before making changes in your Production site. Your team may have received Sandbox access during Onboarding. You can access the Sandbox site by going to {your school’s subdomain}.admin.sandbox-12twenty.com. If you are still having issues accessing Sandbox, please reach out to support@12twenty.com.
Why won't my Sandbox credentials work after a Sandbox scrub?
Every six weeks, the sandbox site copies down from Production. This means that if your password for Sandbox was different than your Production password, it may have been reverted to your Production password after the scrub. Please use your Production password to access the Sandbox site. If that doesn't work, please reach out to support@12twenty.com so that we can reset your Sandbox password. For more information on the Sandbox scrub, please see this article.