Lookup user and service id by user identifier

GET

/dr/v2/users/{type}/{id}

const url = 'https://sender.sandbox-api.kivra.com/dr/v2/users/nationalidentitynumber/example?hashed=true';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://sender.sandbox-api.kivra.com/dr/v2/users/nationalidentitynumber/example?hashed=true'

The user lookup checks if a given identifier is connected to a Kivra user. We recommend to hash (sha256) the identifier before doing the lookup except if a cardtoken is used. The cardtoken MUST NOT be hashed.

NOTE! A user can reject receipts from any chain so if a partner token is used when doing the user lookup a chain id must be passed.

Difference from v1: This endpoint returns the user’s service id on success. If the Kivra user could not be identified, an HTTP 400 status code with “person not found” is returned.

Access scope

PARTNER
CHAIN
STORE

Parameters

Path Parameters

type

required

string

Allowed values: nationalidentitynumber mobilephone email cardtoken

The type of identifier given

required

string

The value of the identifier

Query Parameters

chain_id

string

The chain ID is required if using a partner token

hashed

required

boolean

default: true

Determinied if the identifier is given as hashed value or in cleartext

Responses

200

User exists and has a service id identifier

application/json

object

service_id

required

The service id identifier connected to the user’s Kivra account

string

Example

{
  "service_id": "15594097555922f97bfeb148d6b9a6ef76f76ebdce"
}

400

Bad request

application/json

ErrorResponse

object

error_code

string

short_message

string

long_message

string

error_detail

Array<string>

Examples

{
  "error_code": "40005",
  "short_message": "bad request",
  "long_message": "person not found"
}

{
  "error_code": "40010",
  "short_message": "bad request",
  "long_message": "unknown url parameter"
}

{
  "error_code": "40012",
  "short_message": "bad request",
  "long_message": "invalid identifier"
}

401

Unauthorized

application/json

ErrorResponse

object

error_code

string

short_message

string

long_message

string

error_detail

Array<string>

Examples

unauthorized

{
  "error_code": "40100",
  "short_message": "unauthorized",
  "long_message": "permission denied"
}

500

Internal server error

application/json

ErrorResponse

object

error_code

string

short_message

string

long_message

string

error_detail

Array<string>

Example

{
  "error_code": "50000",
  "short_message": "internal server error",
  "long_message": "unknown error ocurred"
}