How to call a REST API via Swagger UI

Every API endpoint in ClearID supports Swagger UI which allows you to test quickly the API without having to format the request in Postman or other REST client tools.

To try out API, you need to have administrator access to your ClearID sandbox account.
More information on Account for dev/test sandbox

1 - Authenticate the swagger UI of the API endpoints

For each API Endpoints the table contains the swagger UI url which is the documentation of the endpoint.

For this example we will use the Identity Service in the dev sandbox environment.
https://identityservice-demo.clearid.io/swagger/

Once you open that page, you must click on Authenticate at the top.

556556

In the Available authorizations Window, please check openid, don't put anything in client_id.
You can now click Authorize.

723723

If the browser is already connected to ClearID, it will redirect you to the login page where you need to put the email and password you received for your ClearID account.

Once this process is completed, an access token (bearer) will be created by the ClearID STS and available for subsequent API calls.

2 - Try your first API call

For this example, we will use a very simple call of the Identity Service that we will list Identities they do not have an external ID.

Identity Service Swagger UI
https://identityservice-demo.clearid.io/swagger

In the swagger UI, locate and expand the call:
GET /api​/v2​/accounts​/{accountId}​/identities List identities by external id

Click on "Try it out"

973973

accountid
This mandatory parameter is required in pretty much all API call.
It's your ClearID account where you have administrator privilege. It can be found just by looking at the URL of the ClearID portal after your authenticate:

In https://demo.clearid.io/fy6uk0m5jx the accountid is fy6uk0m5jx
When building a generic integration, the accountid should be read from a JSON config file that can be downloaded from the ClearId Portal. see Authentication for more information on the JSON file.

externalid
Put 123 as value for this example.
The externalid should be a unique Identifier coming from your employee management system, it should be something immutable that can be used as a unique key to link an Identity between ClearID and the source of truth (HR, Payroll, DB...)

continuation
Leave this parameter empty for this example.
This token is required if you have a lot of identities that correspond to the same external id, the system will return the first batch of Identities and provide a continuation token in the response which will return the next batch of identities.
In summary, for the first call, you should never provide any value to get the first batch.

Click on Execute.

At this point, the API should return 200 Sucess with an empty array because no Identity has the external ID "123"

{
  "identities": []
}

3 - Modify your own Identity in the web portal

Open the clearID dev sandbox environment, the URL you received by email should be:
https://demo.clearid.io

1- Click on My Profile in the top menu
2 - Click on Manage on the left menu.
NB: If you don't have the manage option, it's because your account is not an administrator.

It should show a page that looks like the one below.
Edit the field External ID and put the value 123

14891489

4 - Try again with external ID

In the Identity Service swagger UI, locate and expand the call:
GET /api​/v2​/accounts​/{accountId}​/identities List identities by external id

Now try again with your accountid and 123 as externalid.

This time the API should return your Identity in the array similar to this below.

{
  "identities": [
    {
      "identityId": "480ea883-cf19-426a-8cd2-1c9fdc3c12ef",
      "eTag": "db69d035bb9e0a5d24d2ae55907e1d8a2f1322f6",
      "status": "Active",
      "firstName": "John",
      "lastName": "Smith",
      "displayName": "John Smith",
      "countryCode": "USA",
      "email": "[email protected]",
      "privateData": {
        "employeeNumber": ""
      },
      "companyData": {},
      "systemData": {
        "partitions": [
          "/cleariddemos/"
        ],
        "externalId": "123",
        "provisioningAttributes": [
          {
            "name": "LEVEL3"
          }
        ]
      },
      "createdBy": "[email protected]",
      "creationDateUtc": "2018-10-30T16:40:30.869477Z",
      "lastModifiedBy": "[email protected]",
      "lastModificationDateUtc": "2021-12-21T16:02:33.0173585Z",
      "ordinal": 5,
      "isDeleted": false
    }
  ]
}