How to connect to the Themis Search API

This article describes how to set up and use the Themis APIs for Screening and/or Monitoring.

Themis’ APIs are a set of simple REST APIs that use the OAuth protocol to authorise each API endpoint. As such a bearer token needs to be generated and used in each request and this is created by calling our identity service using a client key and secret. The next section will explain how to generate a bearer token.

1. Create a Bearer Token

1.1 Get your Client Id

Log in to themissearch.com as an administrator and select the Admin drop down off the top menu.
Select the Web API Settings option.
You will now be able to see your Client ID - click on show to view it and copy it for use in creating the bearer token.
Make a copy of this code and store securely for use later in generating the bearer token.

Note also that from here you can click on the Documentation link to view the API swagger documentation that can also be found here: https://api.themissearch.com

1.2 Get your account secret.

To get or refresh your account secret key, click on the Refresh Secret button.
You will get a warning, click 'Yes' if you are happy to change the secret key.
Once you click yes, then a new secret will be generated and displayed as illustrated in the image below:
Copy this code and store it in a secure location along with your client id. If the secret is lost or is compromised then return here to refresh but note that all other usages of the old secret will be unable to connect

1.3 Generate a bearer token

To generate a bearer token, you need to make a request to the Themis identity service token endpoint using your client ID and secret.
1. ```
https://identity.themissearch.com/connect/token
```

Call this, passing in the Client Id and Secret you generated above. See Curl example below.

curl -d "client_id=CLIENT ID" -d "client_secret=SECRET" -d "grant_type=client_credentials" "https://identity.themissearch.com/connect/token"

This will return your access token that can then be passed to each of the APIs you wish to use. The token generally lasts for up to 24 hours after which it will expire and require refreshing.

{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjQ1RjkyQTRDQUZDMjdERkM3MTY3MEMzMTVFNzZDasasTUxIiwidHlwIjoiYXQrand0In0.eyJuYmYiOjE2ODM4OTkxMjIsImV4cCI6MTY4Mzk4NTUyMiwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS50aGVtaXNzZWFyY2g...JIG1OZig58u5PP0nPBUk-o3yzE71CG_bZbHMdqN4bea265avEgvrHcoNKU1ntymtry6UstfsGsvgMi7AvJHhqVxki0ZFLDJb7fhK8atqMuAk88vbtB7MrxKjSdhUQnS_7xkAJiLQl6HSiNspkujGHdqQfD2ok0i0IT_JVzIupg9bNtr-I4mO5foN6LVf5cRWWFjPYECCBc1yeKVB9dgqP61ceiKzl_BmcXdt-FDWkFizxU0YHxydQ1rEDaiscZlrr42bzhlA30nla9vaq9X5B3Wl6lVY3uFJcaocpeSPYy_7kFeazsBw","expires_in":86400,"token_type":"Bearer","scope":"api1"}

Store this access token for use in calling any of the APIs available to your subscription.

2. Calling an API

As stated above you need to pass the access (bearer) token with each API within the header
At this point you can use the token directly from our swagger documentation page. Just click on the Authorize button.
Copy the access_token part of the JSON returned above.
NOTE: You need to prefix the token with the word Bearer followed by a space.
Press the Authorise button. You can now try any of the APIs that are available to your subscription.
You should add 1 against the version number for each API call you try. Note that this number may change as new versions of the APIs are released.
Below is a curl example using the bearer token generated previously to return the summary of your monitored clients.

curl -X 'GET' \ 

  'https://api.themissearch.com/v1/monitoring/summary' \ 

  -H 'accept: text/plain' \ 

  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjQ1RjkyQTRDQUZDMjdERkM3MTY3MEMzMTVFNzZDNTUxIiwidHlwIjoiYXQrand0In0.eyJuYmYiOjE2ODM4OTY4NTcsImV4cCI6MTY4Mzk4MzI1NywiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS50aGVtaXNzZWFyY2guY29tIiwiY2xpZW50X2l...IGKlUxvvzVI0aK0wJXKMtOamZDThjo9Km2HguEKxlQEI6ht6LqE3m-8XBsrsz43Fc59rBISA80Jwx-pF8kM8L_ZtzHd0N7JcpcuEI9IEs-lOPybw720ysSyGbRZWzYrKrgWFmKsr-pNABmVfssepG019CmlJSeJmCnXcA-J8p2IY-jtt7bzEa1MMqBCurCKe90sENLMDTnox5KvLztJRjkGSSNJtlDIH-XVLgFbdVaQENzvs3-mFc5OegWEbh3z13-q5M3LLfMdu7XA'

If successful then this will return the summary similar to this shown below:

{ 

  "data": { 

    "advMedia": { 

      "alerts": 13, 

      "change": 0, 

      "total": 17 

    }, 

    "legal": { 

      "alerts": 6, 

      "change": 0, 

      "total": 13 

    }, 

    "peps": { 

      "alerts": 4, 

      "change": 0, 

      "total": 10 

    }, 

    "sanctions": { 

      "alerts": 5, 

      "change": 0, 

      "total": 8 

    }, 

    "total": { 

      "alerts": 25, 

      "change": 0, 

      "total": 36 

    } 

  }, 

  "errors": null, 

  "isSuccess": true 

}

For full schema API documentation please refer to the following swagger page: https://api.themissearch.com

3. Using Postman

We have provided a postman collection and to use this then follow these instructions:

Start by clicking on the collection name “Themis Search API” to update the variables used throughout.
Set the clientId and Secret with your own keys.
Note that there is a bearer token here too, we are going to create one and come back here to copy the value we generated. Next up we need to create the bearer token.
Click on 1. Set up / Create Bearer Token.
Scroll to the bottom and Click on Grant New Access Token.
You should see the authentication complete message. Click Proceed.
You will now see this something like this, click on 'Use Token':
Now, scroll back up to the top .
Here you will see the token, highlight the token and copy it.
Now click back on the collection name again and update the value of the bearer token.
You are ready to play with the APIs! Remember the token will eventually expire and you will need to repeat these steps again to reuse the APIs.
One final thing to mention. You may have noticed that there are 2 additional variables here denoting the unique id for an individual and one for a business. You can change these here but they are used for both the monitoring and screening APIs. As their names suggest these are unique so if you create an individual in screening, then you will get an error message in monitoring unless you move it and delete it.

If you require any further support please reach out to your Customer Success Manager!