GraphQL - TargetData

The most convenient way to explore our TargetData API is to use browser-based GraphQL Playground IDE hosted on our server.

https://targetdata.test.teavaro.systems/graphql
As you can see in the below screenshot, the tool provides:

Context-aware autocompletion & error highlighting.
Interactive, multi-column docs with keyboard support.
Ability to execute requests right away from the UI.

API Access

TargetData GraphQL API uses Authorization: Bearer scheme in order to authenticate the user.
You have to provide a valid access token in every request against our /graphql endpoint.
Access tokens are generated using an offline refresh token, which is bound to your account.

Create an offline refresh token

In order to create an offline refresh token you need to open the following URL in your browser:

CODE

https://targetdata.test.teavaro.systems/auth/offline-token

After filling in your credentials you will be redirected to a page, which displays your offline refresh token. This type of token never expires. You should keep it in a secure vault and use it as a secret in your client application targeting our GraphQL endpoint.

Create access tokens

In order to create a new access token you have to execute a POST request against our /auth/token endpoint.

Our endpoint accepts POST url-encoded forms with a mandatory refresh_token field.

Example curl:

CODE

curl -X POST \ 
  -d "refresh_token=YOUR_OFFLINE_REFRESH_TOKEN" \
  "https://targetdata.test.teavaro.systems/auth/token"

Example response:

JSON

{
  "access_token": "ZrSmxmU0FFbVo5VS16NTlBczdTMF9iVW5VZTAyOE52MmtUMVM4In0.eyJleHAiOjE2NDkxNjI1MjYsImlhdCI6MTY0OTE1ODkyNiwiYXV0aF90aW1lIjoxNjQ5MDgwNTQzLCJqdGkiOiIyYjI5NjIwZi05YTgyLTRhNjAtODU0ZC1lOGExZjYxNjgxMTQiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLnRlYXZhcm8ubmV0L2F1dGgvcmVhbG1zL3Rlc3RlbnYiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZGY4OTQ3NTgtNTMxYi00ODk4LTgyZmItOGY5ZjQ3ODYxYzk1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidGFyZ2V0ZGF0YS1ncWwiLCJzZXNzaW9uX3N0YXRlIjoiZjM5NmUyMTAtZGVlYi00MDczLWE3N2YtMWYxYTBkYzBjZjk0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwczovL3RhcmdldGRhdGEtYXBpLnR2dGVzdGVudjEubmV0LyJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgb2ZmbGluZV9hY2Nlc3MgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwibmFtZSI6IlRhcmdldERhdGEgR3JhcGhRTCIsInByZWZlcnJlZF91c2VybmFtZSI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIiwiZ2l2ZW5fbmFtZSI6IlRhcmdldERhdGEiLCJmYW1pbHlfbmFtZSI6IkdyYXBoUUwiLCJlbWFpbCI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIn0.osEJTtz07R8XTGCEXWPZ3pcwEUvW-TkOhCon9l7Qr_m0BfkiuqQrKkSfq-76Nri_zXO6rnGsCuAbE0lZKZqpun1CzqyUL_YwQBOQ9kwv5nZG065n4fyhhzqiSSjBobqbJYLwylNVFsDUxif_TWY3Acp4LSVII07XlVy5FUOde-Zzu99hsbZY11oFiZOOdSd7PpIf7t1cYZP0uTFml_s2pNGxHLD5_TZ2i86uOVWj7D8guCI7PUVZ8T7rigaLT5FM2lwtfF9VbH3N29M-PvXuqAz1kB-HBy5B0JOCkgyYnoxbhnQroyiSTUS92bzSd7fVoQcXkbL3yg_L3yEh3gt7xw",
  "expires_in": 3600,
  "refresh_expires_in": 0,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiYTk4",
  "token_type": "Bearer",
  "session_state": "f396e211-deeb-4073-c57f-1f1a0dc0cf94",
  "scope": "email offline_access profile"
}

Your access token is available in the access_token field and is valid for 3600 seconds (1 hour). If your access token expires, our API will respond with HTTP status code 401. In such a case, you should simply create a new one using the described method and execute the same query again.

It is possible to have multiple access tokens at the same time. Use your access token in the Authorization: Bearer scheme.
Header name: Authorization
Header value: Bearer <your-access-token>

Creating JSON Request

As soon as you obtain your first access token, you are ready to use our GraphQL API programmatically. The most common way to make GraphQL requests from your client application is to construct POST JSON requests against our /graphql endpoint.

Minimal example

Let’s consider the following query:

CODE

query MyExample {
  personTargetDataByUmid(umid: "53090af3-5023-46d7-9f1d-05ccb09a7835") {
    profileId
    owner
    category
  }
}

Your query will be placed into query JSON string. It is necessary to escape the query, so it has no offending characters that could prevent parsing.

Escaped and minified query:

CODE

query MyExample {\r\n  personTargetDataByUmid(umid: \"53090af3-5023-46d7-9f1d-05ccb09a7835\") {\r\n    profileId\r\n    owner\r\n    category\r\n  }\r\n}

Please note that it is possible to drop query MyExample prefix from the above. The most important part is surrounded by the curly brackets. The brackets themselves have to be included!

The next step is to place your query in a JSON request:

CODE

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type:application/json" \
  -d '{"query": "{ YOUR_STRINGIFIED_GQL_QUERY }"}' \
  "https://targetdata.test.teavaro.systems/graphql"

Example request:

CODE

curl -X POST \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJDOF9TREZrSmxmU0FFbVo5VS16NTlBczdTMF9iVW5VZTAyOE52MmtUMVM4In0.eyJleHAiOjE2NDkxNjY0NTQsImlhdCI6MTY0OTE2Mjg1NCwiYXV0aF90aW1lIjoxNjQ5MDgwNTQzLCJqdGkiOiJhZWU0Y2FlZS0yYmY5LTRjYzUtYTc1Yi03ZjhlNTJmMjY0OTUiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLnRlYXZhcm8ubmV0L2F1dGgvcmVhbG1zL3Rlc3RlbnYiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZGY4OTQ3NTgtNTMxYi00ODk4LTgyZmItOGY5ZjQ3ODYxYzk1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidGFyZ2V0ZGF0YS1ncWwiLCJzZXNzaW9uX3N0YXRlIjoiZjM5NmUyMTAtZGVlYi00MDczLWE3N2YtMWYxYTBkYzBjZjk0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwczovL3RhcmdldGRhdGEtYXBpLnR2dGVzdGVudjEubmV0LyJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgb2ZmbGluZV9hY2Nlc3MgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwibmFtZSI6IlRhcmdldERhdGEgR3JhcGhRTCIsInByZWZlcnJlZF91c2VybmFtZSI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIiwiZ2l2ZW5fbmFtZSI6IlRhcmdldERhdGEiLCJmYW1pbHlfbmFtZSI6IkdyYXBoUUwiLCJlbWFpbCI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIn0.WglQpxsxCATpCqLM49T8ypiIpoVqmg8BSRVI2qdYFBX5x5M0EhcrhMa7snBHdkCHg8XmKX1gYapGol-1ivaAkHphaPnL_fw8KNPnkbPna6ksWOp1ZBna6x5YBqEU1okTpf-W8w4qPZaH0hTHyBzU6tmydXV-jlPgnB3vdYZBDLlJtlpDLQnpOvPfHhWn3O9k1SZn3EJdoJWgcmEw-SaQKQlJL30acNRaRtcGLPGb-3AKoKyBfJWDbwkCNI8PZ4Ll_YdGmar9YPG4SjNMqpU8NBiTLK8VlBgp-AIzecvT3T8k7FE7NiTmXI_Xd5DyVK3TEWL5B2Gm3Ydkvt4JvOiiMA" \
  -H "Content-Type:application/json" \
  -d '{
    "query": "{ personTargetDataByUmid(umid: \"53090af3-5023-46d7-9f1d-05ccb09a7835\") {\r\n    profileId\r\n    owner\r\n    category\r\n  }\r\n}"
  }' \
  "https://targetdata.test.teavaro.systems/graphql"

Example response:

JSON

{
  "data": {
    "personTargetDataByUmid": {
      "profileId": "6233144041a27827a2e1139c",
      "owner": "stub",
      "category": "mobile"
    }
  }
}

Example with variables

A bit more complicated example using GraphQL variables:

CODE

query PersonTargetDataByAnyId(
  $idName: String!,
  $idValue: String!
) {
  personTargetDataByAnyId(
    idName: $idName,
    idValue: $idValue
  ) {
    profileId
    identifiers {
      name
      value
    }
  }
}

Once more, let’s escape and minify the query:

CODE

query PersonTargetDataByAnyId(\r\n  $idName: String!,\r\n  $idValue: String!\r\n) {\r\n  personTargetDataByAnyId(\r\n    idName: $idName,\r\n    idValue: $idValue\r\n  ) {\r\n    profileId\r\n    identifiers {\r\n      name\r\n      value\r\n    }\r\n  }\r\n}

As $idName and $idValue imply that we are using variables, we have to prepare a separate JSON object with variables:

JSON

{
    "idName": "msisdn-sha2",
    "idValue": "1b2a8eafa1cbe1ab3861e9b1789b58838588473551c9f24824afa10a251cd25c"
}

Variables JSON could be minified, but there’s no need to escape it:

JSON

{"idName": "msisdn-sha2","idValue":"1b2a8eafa1cbe1ab3861e9b1789b58838588473551c9f24824afa10a251cd25c"}

Finally, we can construct our request, which could look like this:

CODE

curl -X POST \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJDOF9TREZrSmxmU0FFbVo5VS16NTlBczdTMF9iVW5VZTAyOE52MmtUMVM4In0.eyJleHAiOjE2NDkxNjY0NTQsImlhdCI6MTY0OTE2Mjg1NCwiYXV0aF90aW1lIjoxNjQ5MDgwNTQzLCJqdGkiOiJhZWU0Y2FlZS0yYmY5LTRjYzUtYTc1Yi03ZjhlNTJmMjY0OTUiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLnRlYXZhcm8ubmV0L2F1dGgvcmVhbG1zL3Rlc3RlbnYiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZGY4OTQ3NTgtNTMxYi00ODk4LTgyZmItOGY5ZjQ3ODYxYzk1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidGFyZ2V0ZGF0YS1ncWwiLCJzZXNzaW9uX3N0YXRlIjoiZjM5NmUyMTAtZGVlYi00MDczLWE3N2YtMWYxYTBkYzBjZjk0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwczovL3RhcmdldGRhdGEtYXBpLnR2dGVzdGVudjEubmV0LyJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgb2ZmbGluZV9hY2Nlc3MgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwibmFtZSI6IlRhcmdldERhdGEgR3JhcGhRTCIsInByZWZlcnJlZF91c2VybmFtZSI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIiwiZ2l2ZW5fbmFtZSI6IlRhcmdldERhdGEiLCJmYW1pbHlfbmFtZSI6IkdyYXBoUUwiLCJlbWFpbCI6InRhcmdldGRhdGEtZ3FsQHRlYXZhcm8uY29tIn0.WglQpxsxCATpCqLM49T8ypiIpoVqmg8BSRVI2qdYFBX5x5M0EhcrhMa7snBHdkCHg8XmKX1gYapGol-1ivaAkHphaPnL_fw8KNPnkbPna6ksWOp1ZBna6x5YBqEU1okTpf-W8w4qPZaH0hTHyBzU6tmydXV-jlPgnB3vdYZBDLlJtlpDLQnpOvPfHhWn3O9k1SZn3EJdoJWgcmEw-SaQKQlJL30acNRaRtcGLPGb-3AKoKyBfJWDbwkCNI8PZ4Ll_YdGmar9YPG4SjNMqpU8NBiTLK8VlBgp-AIzecvT3T8k7FE7NiTmXI_Xd5DyVK3TEWL5B2Gm3Ydkvt4JvOiiMA" \
  -H "Content-Type:application/json" \
  -d '{
    "query": "query PersonTargetDataByAnyId(\r\n  $idName: String!,\r\n  $idValue: String!\r\n) {\r\n  personTargetDataByAnyId(\r\n    idName: $idName,\r\n    idValue: $idValue\r\n  ) {\r\n    profileId\r\n    identifiers {\r\n      name\r\n      value\r\n    }\r\n  }\r\n}",
    "variables": {"idName": "msisdn-sha2","idValue":"1b2a8eafa1cbe1ab3861e9b1789b58838588473551c9f24824afa10a251cd25c"}
  }' \
  "https://targetdata.test.teavaro.systems/graphql"

Schema

See TargetData Schema Reference.