Operations with users by external identifier

Users API allows you to perform operations on identifiers from an external system. The API does not check the uniqueness of external identifiers when creating or updating a user account record. It is the responsibility of the API caller to ensure that all external identifiers are specified in all API calls and are unique.

Each integration is tied to some administrative user. And each such user must create his own API key to work with the API. External identifiers are isolated within this API key. In other words, external identifiers are tied to a specific API key.

If there is a need for integration with different external systems and each system has its own subset of unique keys, then it is necessary to create a API key for each system.

If different systems use the same unique identifier, then it is preferable to use the same API key but generate different API tokens for each integration.

Get a user by external identifier

Read a specific user information by external identifier.

Request

GET /api/v2/users/external_id/{external_id}/

Request parameters

Parameter	Type	Description
external_id	integer	External user ID.

Example

This is an example of reading information about a specific user account by external identifier.

Request URL

https://lms.example.com/api/v2/users/external_id/ID10-05113/

Response body

{
  "id": 1523,
  "email": "jsmith@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "address": "1 Main street",
  "address2": "",
  "city": "Columbus",
  "state": "OH",
  "zip": "43215",
  "country": "US",
  "expirationDate": "",
  "externalId": "ID10-05113",
  "createdDate": "2024-01-15T14:58:41Z",
  "updatedDate": "2024-02-01T10:25:01Z"
}

Curl

curl -X 'GET' \
  'https://lms.example.com/api/v2/users/external_id/ID10-05113/' \
  -H 'accept: application/json'

Create a user with external identifier

Use the same POST method specified in Users section. You need to specify externalId parameter to specify an external identifier for a user record.

Example

This is an example of creating a user with external identifier "ID10-05113".

Request URL

https://lms.example.com/api/v2/users/

Request body

{
  "email": "jsmith@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "loginName": "jsmith",
  "externalId": "ID10-05113"
}

Response body

{
  "id": 1523,
  "email": "jsmith@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "address": "1 Main street",
  "address2": "",
  "city": "Columbus",
  "state": "OH",
  "zip": "43215",
  "country": "US",
  "expirationDate": "",
  "externalId": "ID10-05113",
  "createdDate": "2024-01-15T14:58:41Z",
  "updatedDate": "2024-02-01T10:25:01Z"
}

Curl

curl -X 'POST' \
  'https://lms.example.com/api/v2/users/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "jsmith@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "loginName": "jsmith",
  "externalId": "ID10-05113"
}'

Update a user by external identifier

Update an existing user account by external identifier.

Required fields: email, firstName, lastName, loginName.

Request

POST {LMS_URL}/api/v2/users/external_id/{external-id}/

Request parameters

Parameter	Type	Description
external_id	integer	External user ID.

Request body

The body of the request is a User object. You must include all required fields. Optional fields can be omitted from the request.

Response

The method returns a user object containing all fields.

Example

This is an example of updating a user's city field by external identifier.

Request URL

https://lms.example.com/api/v2/users/external_id/ID10-05113/

Request body

{
  "city": "Dublin"
}

Response body

{
  "id": 1523,
  "email": "jsmith@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "address": "1 Main street",
  "address2": "",
  "city": "Columbus",
  "state": "OH",
  "zip": "43215",
  "country": "US",
  "expirationDate": "",
  "externalId": "ID10-05113",
  "createdDate": "2024-01-15T14:58:41Z",
  "updatedDate": "2024-02-01T10:25:01Z"
}

Curl

curl -X 'POST' \
  'https://lms.example.com/api/v2/users/external_id/ID10-05113/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "city": "Dublin"
}'

Delete a user by external identifier

This method marks the user account as deleted by external identifier.

Request

DELETE {LMS_URL}/api/v2/users/external_id/{external_id}/

Request parameters

Parameter	Type	Description
external_id	integer	External user ID.

Response

The method returns HTTP code 204 if the user account was successfully deleted.

Example

This is an example of deleting a user account by external identifier.

Request URL

https://lms.example.com/api/v2/users/external_id/ID10-05113/

Curl

curl -X 'DELETE' \
  'https://lms.example.com/api/v2/users/external_id/ID10-05113/' \
  -H 'accept: application/json'

Last modified: 06 January 2025