1030: Entity Lookup

Fetches selected data points for an entity

Endpoint ID:

1030

Method:

POST

URL:

/lookup/entity/id/{entity-id}

/lookup/entity/ext-key/{ext-key}/{ext-type}

/lookup/match/{match-id}

entity-id

Rubiq entity ID that uniquely identifies an account to evaluate the scheme for

ext-key

External key that uniquely identifies an account to evaluate the scheme for

ext-type

Type of external key

match-id

The ID of a Rubiq Cloud Match, used to perform the match lookup based on request body parameters

Request body:

JSON data describing the lookup scope (response fields).

Required fields
	match	When the lookup URL includes a `match-id`, then the `match` body field is required. It is not used when performing `entity-id` or `ext-key`/`ext-type` lookups. `match` is a JSON object containing match fields.
Optional fields
	scope	The fields that should be included in the response. When excluded, all fields are included. Possible fields are: `data`, `children`, `terms`, `consents`

Example entity lookup, /lookup/entity/id/123456

{
  "scope": [ "data", "children", "terms", "consents" ]
}

Example match lookup, /lookup/match/123

{
  "match": {
    "phone": "45454545",
    "email": "mailbox@mailserver.com"
  },
  "scope": [ "consents" ]
}

A JSON response including the requested fields:

Example: "scope": [ "data", "children" ]

{
  "data": {
    "id": 123456,
    "name": "John Doe",
    "email": "mailbox@mailserver.com"
  },
  "children": [
    {
      "id": 1234,
      "type": 2,
      "name": "Sarah"
    },
    {
      "id": 5678,
      "type": 2,
      "name": "Michael"
    }
  ]
}

Example: "scope": [ "terms" ]

{
  "terms": [
    {
      "isActive": true,
      "isWithdrawn": false,
      "isExpired": false,
      "terms": {
        "id": "64d0cd4c-2378-4907-b522-188d8a89c2da",
        "name": "General terms and conditions",
        "version": "4.2",
        "isMostRecentVersion": true
      },
      "acceptance": {
        "timestamp": "2025-08-18T14:26:19",
        "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5",
        "contextData": {}
      },
      "consents": [
        {
          "permissionID": "00f3709c-87d6-4a66-9747-53371432a859",
          "permissionName": "Contact me",
          "isActive": false,
          "isWithdrawn": true,
          "isExpired": false,
          "isDeclined": false,
          "acceptance": {
            "timestamp": "2025-08-18T14:26:19",
            "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5"
          },
          "withdrawal": {
            "timestamp": "2025-08-23T11:52:06",
            "sourceID": "f9198a1c-19b7-4572-870a-810debf80326"
          }
        },
        {
          "permissionID": "63e157ee-434d-4b77-9f71-b02708b3a546",
          "permissionName": "Contact me via phone",
          "isActive": false,
          "isWithdrawn": false,
          "isExpired": false,
          "isDeclined": true,
          "declined": {
            "timestamp": "2025-08-18T14:26:19",
            "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5"
          }
        }
      ]
    }
  ]
}

Example: "scope": [ "consents" ]

{
  "consents": [
    {
      "permissionID": "00f3709c-87d6-4a66-9747-53371432a859",
      "permissionName": "Contact me",
      "isActive": false,
      "isWithdrawn": true,
      "isExpired": false,
      "isDeclined": false,
      "acceptance": {
        "timestamp": "2025-08-18T14:26:19",
        "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5"
      },
      "withdrawal": {
        "timestamp": "2025-08-23T11:52:06",
        "sourceID": "f9198a1c-19b7-4572-870a-810debf80326"
      },
      "terms": {
        "id": "64d0cd4c-2378-4907-b522-188d8a89c2da",
        "name": "General terms and conditions",
        "version": "4.2"
      }
    },
    {
      "permissionID": "63e157ee-434d-4b77-9f71-b02708b3a546",
      "permissionName": "Contact me via phone",
      "isActive": false,
      "isWithdrawn": false,
      "isExpired": false,
      "isDeclined": true,
      "declined": {
        "timestamp": "2025-08-18T14:26:19",
        "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5"
      },
      "terms": {
        "id": "64d0cd4c-2378-4907-b522-188d8a89c2da",
        "name": "General terms and conditions",
        "version": "4.2"
      }
    },
    {
      "permissionID": "d9cf0485-d3f8-4972-b165-649ca4cc1680",
      "permissionName": "Allow cookies",
      "isActive": true,
      "isWithdrawn": false,
      "isExpired": false,
      "isDeclined": false,
      "acceptance": {
        "timestamp": "2025-02-10T09:14:44",
        "sourceID": "f1a677d6-9741-486e-9b0c-e756a69288d5"
      }
    }
  ]
}

Status codes:

200

Entity fetched successfully

404

The entity was not found

The following sub codes may be returned:

404.1	Entity not found
404.2	External entity not found
404.4	Match `match-id` not found
404.5	No match was found for the provided match fields