You can define custom fields for users on your domain by adding custom user schemas to the domain. You can use these fields to store information such as the projects your users work on, their physical locations, their hire date, or whatever else fits your business needs.
To get started, you can create one or more schemas to define the custom fields that make sense for your domain. You can specify a number of attributes, such as the name of the field, the type (string, boolean, integer, etc), whether it's single- or multi-valued, and whether its values are viewable by any user in your domain or only administrators and the associated user.
Once a schema is defined, the custom fields behave just like standard fields. You can set them
when updating users on your domain, fetch them with
users.get
and
users.list
, and also
search for custom fields.
Set custom fields in a user profile
To update or create a user, create a customSchemas
property and
add it to the user resource.
Inside the customSchemas
property, the custom fields are grouped by schema in
standard JSON format:
"customSchemas": { "schema1": { "field1": "value1", "field2": [ { "value": "value2a" }, { "value": "value2b" }, ... ], ... }, "schema2": { "field3": "value3", ... }, ... }
Single-valued custom fields are set as simple key-value pairs, like "field1": "value1"
.
Multi-valued custom fields are set as arrays of objects, much like the standard multi-value fields
in the API such as addresses
and phones
. These value objects support
the following keys:
Keys | |
---|---|
value |
The value to be stored, required. |
type |
Type of the value, optional. Possible values are:
|
customType |
Custom type of the value, optional. Should be used when type is set to custom . |
If a custom field in a schema is not specified at update time, it is left unchanged. If a schema
itself is not specified in customFields
at update time, all custom fields in that schema are
left unchanged. To delete a custom field or a custom schema from a profile, you must set it to
null
explicitly:
"schema1": { "field1": null // deletes field1 from this profile. }
JSON request
The call in the example below updates a user and sets values for the
employmentData
custom schema:
PATCH https://www.googleapis.com/admin/directory/v1/users/liz@example.com
{ "customSchemas": { "employmentData": { "employeeNumber": "123456789", "jobFamily": "Engineering" "location": "Atlanta", "jobLevel": 8, "projects": [ { "value": "GeneGnome" }, { "value": "Panopticon", "type": "work" }, { "value": "MegaGene", "type": "custom", "customType": "secret" } ] } } }
Read custom fields in a user profile
You can fetch custom fields in a user profile by setting the projection
parameter in a users.get
or users.list
request
to custom
or full
.
Search custom fields in a user profile
You can search within custom fields using the query
parameter in
a users.list
request.
You request the custom field with a schemaName.fieldName
syntax. For example:
employmentData.projects:"GeneGnome"
returns all employees that work on project GeneGnome. The query
employmentData.location="Atlanta" employmentData.jobLevel>=7
returns all employees in Atlanta above job level 7. For more information, see Search Users.
Create a custom user schema
A custom user schema can be added to all of your Google Workspace account's domains.
To create a custom user schema in your domains, use the following POST
request
and include the authorization described in
Authorize requests. For the
request query string properties, see the
API Reference.
POST https://www.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas
All create requests require you to submit the information needed to fulfill the request. If you are using client libraries, they convert the data objects from your chosen language into JSON data formatted objects.
JSON request
The following JSON shows a sample request to create a custom schema. For the full list of request and response properties, see the API Reference.
{ "schemaName": "employmentData", "fields": [ { "fieldName": "EmployeeNumber", "fieldType": "STRING", "multiValued": "false" }, { "fieldName": "JobFamily", "fieldType": "STRING", "multiValued": "false" } ] }
Limits
- The maximum number of custom schemas allowed in an account is 100.
- The maximum number of custom fields allowed in an account is 100.
- The maximum number of characters allowed in a
string
field for a single-valued custom field is 500. For multi-valued custom fields, the number of elements allowed depends on the size of the assigned values. For example, you can add 150 values of 100 characters each or 50 values of 500 characters each. - The characters allowed in custom schemas and field names are alphanumeric characters,
underscores (
_
), hyphens (-
). - Changing the type of a field is not allowed.
- A single-valued field can be made multi-valued, but the inverse operation is not allowed.
- It is not possible to rename custom schemas or fields.
A successful response returns an HTTP 201 status code. Along with the status code, the response returns the properties for the new custom schema.
Update a custom user schema
To update a custom schema, use the following PUT
request and include the
authorization described in
Authorize requests. The
schemaKey
can be the schema name or the unique schema id
. For the
request and response properties, see the
API Reference.
PUT https://www.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey
JSON request
In the example below, the schema employmentData
contained a
JobFamily
field when originally created. The request is updating
employmentData
to contain only an EmployeeNumber
field:
PUT https://www.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData
{ "kind": "admin#directory#schema", "schemaId": "dKaYmUwmSZy5lreXyh75hQ==", "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"", "schemaName": "employmentData", "fields": [ { "kind": "admin#directory#schema#fieldspec", "fieldId": "21_B4iQIRY-dIFGFgAX-Og==", "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"", "fieldType": "STRING", "fieldName": "EmployeeNumber", "multiValued": "false" } ] }
All update requests require you to submit the information needed to fulfill the request.
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the updated schema resource.
Retrieve a custom user schema
To retrieve a custom schema, use the following GET
request and include the
authorization described in
Authorize requests. The
schemaKey
can be the schema name or the unique schema id
. For the
request and response properties, see
API Reference.
GET https://www.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey
JSON response
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the custom schema.
{ "kind": "admin#directory#schema", "schemaId": "dKaYmUwmSZy5lreXyh75hQ==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"", "schemaName": "employmentData", "fields": [ { "kind": "admin#directory#schema#fieldspec", "fieldId": "21_B4iQIRY-dIFGFgAX-Og==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"", "fieldType": "STRING", "fieldName": "EmployeeNumber" }, { "kind": "admin#directory#schema#fieldspec", "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"", "fieldType": "STRING", "fieldName": "JobFamily" } ] }
Retrieve all custom user schemas
To retrieve all the custom schemas in the same account, use the following GET
request and include the authorization described in
Authorize requests.
GET https://www.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas
For the request and response properties, see the API Reference.
JSON response
In this example, all custom schemas for my_customer
are returned:
GET https://www.googleapis.com/admin/directory/v1/customer/my_customer/schemas
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the custom schemas for the account:
{ "kind": "admin#directory#schemas", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"", "schemas": [ { "kind": "admin#directory#schema", "schemaId": "dKaYmUwmSZy5lreXyh75hQ==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"", "schemaName": "employmentData", "fields": [ { "kind": "admin#directory#schema#fieldspec", "fieldId": "21_B4iQIRY-dIFGFgAX-Og==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"", "fieldType": "STRING", "fieldName": "EmployeeNumber" }, { "kind": "admin#directory#schema#fieldspec", "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==", "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"", "fieldType": "STRING", "fieldName": "JobFamily" } ] } ] }