This article explains 12twenty’s use of attributes, custom attributes, lookup IDs, and the options endpoint for managing data in the 12twenty API.
Sections:
- Attributes and Attribute IDs
- Custom Attributes
- Lookup IDs and Options
- Modifying attributes with the API
Attributes and Attribute IDs
12twenty’s API stores attributes in the /api/v2/attributes endpoint, this endpoint contains all the attributes added to your site under Site Management > Site Settings > Attributes.
Sending a GET request to this endpoint returns a list of all attributes for all modules on your site. Each attribute has a Short Display Name and Long Display Name which match the fields in 12twenty’s User Interface.
Tip: You can Use the LookupDisplayName or ShortDisplayName and CTRL + F (CMD + F on Mac) to find a specific attribute in the response.
Read-Only Access
All properties of an attribute that can be edited in the UI are visible in the API, but attributes cannot be modified or created via the API. The /attributes endpoint is read-only.
Example Response: "Exchange Student" Attribute
GET {site}.admin.12twenty.com/api/v2/attributes
This endpoint returns all attributes stored in your site.
{
"Id": 1000046,
"Name": "is_exchange_student",
"ShortDisplayName": "Exchange Student",
"LongDisplayName": "Exchange Student",
"EntityTypeId": 1001,
"EntityTypeName": null,
"CustomFormId": null,
"FieldTypeId": 2,
"FieldTypeName": "Radio Button (Yes/No)",
"IsCore": true,
"IsStandard": true,
"ValuePropertyNames": [
"IsExchangeStudent"
],
"DisplayPropertyNames": [
"IsExchangeStudent"
],
"LookupId": null,
"LookupName": null,
…
},
In the above example for the “Exchange Student” attribute, the ID is 1000046. This ID is used to query a specific attribute (instead of the whole list) by sending a GET to /api/v2/attributes/{AttributeID}.
Custom Attributes
Custom attributes are created by an admin on your site instance in the 12twenty UI by clicking “Add new attribute.”
These are also available at the /attributes endpoint and have an attribute ID:
Example Response: "Favorite Snack" Custom Attribute
GET {site}.admin.12twenty.com/api/v2/attributes
{
"Id": 10888805130031,
"Name": null,
"ShortDisplayName": "Favorite Snack",
"LongDisplayName": "What is your favorite snack food?",
"EntityTypeId": 1001,
"EntityTypeName": "Student",
"CustomFormId": null,
"FieldTypeId": 1,
"FieldTypeName": "Dropdown (Single Select)",
"IsCore": false,
"IsStandard": false,
"IsMappedList": false,
"IsShared": false,
"ParentAttributeId": null,
"ParentAttribute": null,
"ParentAttributeValue": null,
"ValuePropertyNames": [],
"DisplayPropertyNames": [],
"LookupId": 10008603102556,
"LookupName": "Snacks",
…
}
Unlike core attributes (e.g., "Exchange Student"), custom attributes have the properties "IsCore" and "IsStandard" set to false.
Custom Attributes in API Responses
When requesting an entity that includes a Custom Attribute (and not the attribute itself) via the API these properties display differently from Core/Standard Attributes. Both examples in this article are part of the “Students & Alumni” module and can be see at the /api/v2/students endpoint, the difference can be seen in the excerpt from the API response for an example student below:
Example Response: Student Profile
GET {site}.admin.12twenty.com/api/v2/students
{
…
"IsExchangeStudent": false,
"CustomAttributeValues": {
"custom_attribute_805": null,
"custom_attribute_10888805135591": null,
"custom_attribute_10888805133691": "True",
"custom_attribute_10888805130030": "15086031054350",
"custom_attribute_10888805130031": "15086031062417",
"custom_attribute_10888805133584": "True",
},
…
“Id”: 1234567890
}
In this API response it is clear which property contains the value for “Exchange Student” (“IsExchangeStudent”), but there are several Custom Attributes in the student's data and none contain either the long or short display name. Custom Attributes are contained in the "CustomAttributeValues" object and follow the format of “custom_attribute_{attributeID}”; so in the above example, the “Favorite Snack” attribute is “custom_attribute_10888805130031.”
The value for the “Favorite Snack” attribute is "15086031062417." This is an ID that references the selection on a student’s profile they chose an option from the Picklist that is associated with “Favorite Snack.” To identify which IDs are associated with the values in a Picklist, you are required to use LookupIDs.
Lookup IDs and Options
Every attribute that has an attached picklist has a Lookup ID. In the above examples, “Exchange Student” has no Lookup ID because it is a Boolean property; it is either true or false. “Favorite Snack” has the Lookup ID “10008603102556” because it is attached to a Picklist and uses a drop-down menu in the 12twenty UI.
Identifying Lookup IDs
A lookup ID can be found in the /attributes endpoint (LookupId field) or the /lookups endpoint. We can also identify an attribute’s lookup ID via the /api/v2/lookups endpoint. This endpoint contains all attributes that have a lookup ID and the response includes several properties of each attribute:
Example Response: Lookup ID for "Favorite Snack"
GET {site}.admin.12twenty.com/api/v2/lookups
{
"Name": "Snacks",
"DisplayName": "Snacks",
"CanFullyManageOptions": true,
"CanEditOptions": true,
"IsCore": false,
"Options": null,
"DoLookupOptionsAllowExtendedOtherData": false,
"LookupTypeOptionAdditionalData": [],
"Attributes": [
{
"ShortDisplayName": "Favorite Snack",
"Entity": "Student"
}
],
"IsInCache": true,
"Id": 10008603102556
},
Retrieving Picklist Options
Once you have the Lookup ID send a GET request to /api/v2/lookups/{LookupID}/options to retrieve available picklist values. In the /lookups endpoint the “ID” is referencing the lookup ID. This value is different from the attribute ID.
Tip: Use the LookupDisplayName or ShortDisplayName and CTRL + F to find the LookupID in the response for this endpoint. However, it may be more intuitive to retrieve the LookupID from the /attributes endpoint instead.
With the LookupID retrieved from either the /attributes or /lookups endpoint it is now possible to request the options for the attached picklist. Send a GET request to /api/v2/lookups/{LookupId}/options and the API will respond with the values for the picklist that can be assigned to the Custom Attribute:
Example Response: Lookup Options
GET {site}.admin.12twenty.com/api/v2/lookups/10008603102556/options
[
{
"Id": 15086031062416,
"Name": "Candy",
"DisplayIndex": 1,
"Group": null
},
{
"Id": 15086031062417,
"Name": "Chips",
"DisplayIndex": 2,
"Group": null
},
{
"Id": 15086031062418,
"Name": "Fries",
"DisplayIndex": 3,
"Group": null
},
{
"Id": 15086031062419,
"Name": "Fruit",
"DisplayIndex": 4,
"Group": null
}
]
These IDs can be used to modify Attributes in the API. Please note that there are also LookupIDs and /options for Core and Standard attributes as long as they are attached to a picklist.
Modifying Attributes with the API
Any endpoint that contains an attribute attached to a Picklist and accepts a PUT or PATCH request allows users to modify its value using IDs from the /options endpoint. In the example with student 1234567890, their “Favorite Snack” is currently "15086031062417", or Chips, but this was entered as “Fries” on a recent student survey and needs to be updated in the 12twenty system. The /students endpoints accept both PUT and PATCH requests, so this can be updated via the API:
Example: Updating "Favorite Snack" Attribute for Student
PATCH {site}.admin.12twenty.com/api/v2/students/{ID}
Request Body:
{
"FirstName": "Abby",
"LastName": "12twenty",
"CustomAttributeValues": {
"custom_attribute_10888805130031": "15086031062418",
},
"GraduationYearId": 2023,
"GraduationClass": 2023
}
Please note:
- PATCH requests only require the fields being updated.
- PUT requests require the full entity object.
Find more information about sending PUT requests to the 12twenty API in the document here.