---
id: service-read-individual-by-mapper-id
title: "Read individual by mapper ID"
description: "Reads the individual that has this `mapperId`: the second ID that you gave the individual, for example its user ID in your mobile app."
sidebar_label: "Read individual by mapper ID"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/consent-management-individual-api/igrant-io-api-documentation
custom_edit_url: null
---

> **Build this with an AI coding agent.** Install the iGrant.io Agent Skills, then ask your agent to build the integration:
>
> ```bash
> npx skills add L3-iGrant/skills
> ```


import ApiTabs from "@theme/ApiTabs";
import DiscriminatorTabs from "@theme/DiscriminatorTabs";
import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
import MimeTabs from "@theme/MimeTabs";
import ParamsItem from "@theme/ParamsItem";
import ResponseSamples from "@theme/ResponseSamples";
import SchemaItem from "@theme/SchemaItem";
import SchemaTabs from "@theme/SchemaTabs";
import Markdown from "@theme/Markdown";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";

<h1 className={"openapi__heading"}>Read individual by mapper ID</h1>

<MethodEndpoint method={"get"} path={"/v4/service/platform/individual/mapper/{mapperId}"}></MethodEndpoint>



Reads the individual that has this `mapperId`: the second ID that you gave the individual, for example its user ID in your mobile app.

This route takes an API key, or a token of the identity provider of the organisation: with such a token the individual can read only its own record, and another mapper ID gets `403`. An individual token and a token of the privacy dashboard login get `403`.

## Request

<details style={{"marginBottom":"1rem"}} className={"openapi-markdown__details"} data-collapsed={false} open={true}><summary style={{}}><h3 className={"openapi-markdown__details-summary-header-params"}>Path Parameters</h3></summary><div><ul><ParamsItem className={"paramsItem"} param={{"description":"Mapper ID of the individual (`mapperId`).","in":"path","name":"mapperId","required":true,"schema":{"type":"string"},"example":"app-user-2002"}}></ParamsItem></ul></div></details><div><div><ApiTabs label={undefined} id={undefined}><TabItem label={"200"} value={"200"}><div>

The individual.

</div><div><MimeTabs className={"openapi-tabs__mime"} schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs className={"openapi-tabs__schema"}><TabItem label={"Schema"} value={"Schema"}><details style={{}} className={"openapi-markdown__details response"} data-collapsed={false} open={true}><summary style={{}} className={"openapi-markdown__details-summary-response"}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}} className={"openapi-markdown__details"}><summary style={{}}><span className={"openapi-schema__container"}><strong className={"openapi-schema__property"}>individual</strong><span className={"openapi-schema__name"}> object</span></span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

A person whose consent the organisation records, for example a customer. The record can point to the person in another system through `externalId`. Keep personal data in it to the minimum that you need.

</div><SchemaItem collapsible={false} name={"id"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"6af081b138e8f33dcf799628","description":"Individual ID. The server sets it. Send it in the `X-ConsentBB-IndividualId` header of the consent record routes."}}></SchemaItem><SchemaItem collapsible={false} name={"externalId"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"customer-1001","description":"Your own ID of the person, for example a customer number. It is unique in the organisation: a second individual with the same external ID gets `409`."}}></SchemaItem><SchemaItem collapsible={false} name={"externalIdType"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"customerNumber","description":"What kind of ID `externalId` is, for example `customerNumber` or `email`."}}></SchemaItem><SchemaItem collapsible={false} name={"identityProviderId"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"ID of the identity provider of the organisation that the person logs in with, if any."}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"Alex Doe","description":"Name of the individual."}}></SchemaItem><SchemaItem collapsible={false} name={"iamId"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"ID of the login account of the individual at the identity service. The server sets it when the individual has an `email`."}}></SchemaItem><SchemaItem collapsible={false} name={"email"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"Email address. With an email address, the server also makes a login account for the individual (for the privacy dashboard). An email address that has an account already gets `400`."}}></SchemaItem><SchemaItem collapsible={false} name={"phone"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"Phone number."}}></SchemaItem><SchemaItem collapsible={false} name={"pushNotificationToken"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"Push notification token of the device of the individual."}}></SchemaItem><SchemaItem collapsible={false} name={"deviceType"} required={false} schemaName={"string"} qualifierMessage={"**Possible values:** [``, `android`, `ios`]"} schema={{"type":"string","description":"Operating system of the device for push notifications. Empty when not set. Any other value gets `400`.","enum":["","android","ios"]}}></SchemaItem><SchemaItem collapsible={false} name={"mapperId"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"A second ID of your choice, for example the ID of the person in a mobile app. It is unique in the organisation: a second individual with the same mapper ID gets `409`."}}></SchemaItem></div></details></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"individual\": {\n    \"id\": \"6af081b138e8f33dcf799628\",\n    \"externalId\": \"customer-1001\",\n    \"externalIdType\": \"customerNumber\",\n    \"identityProviderId\": \"string\",\n    \"name\": \"Alex Doe\",\n    \"iamId\": \"string\",\n    \"email\": \"string\",\n    \"phone\": \"string\",\n    \"pushNotificationToken\": \"string\",\n    \"deviceType\": \"\",\n    \"mapperId\": \"string\"\n  }\n}"} language={"json"}></ResponseSamples></TabItem><TabItem label={"Example"} value={"Example"}><ResponseSamples responseExample={"{\n  \"individual\": {\n    \"id\": \"6af0821c38e8f33dcf79962e\",\n    \"externalId\": \"customer-1002\",\n    \"externalIdType\": \"customerNumber\",\n    \"identityProviderId\": \"\",\n    \"name\": \"Sam Doe\",\n    \"iamId\": \"\",\n    \"email\": \"\",\n    \"phone\": \"\",\n    \"pushNotificationToken\": \"<push-notification-token>\",\n    \"deviceType\": \"ios\",\n    \"mapperId\": \"app-user-2002\"\n  }\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"401"} value={"401"}><div>

The API key or the token is missing or not valid.

</div><div><MimeTabs className={"openapi-tabs__mime"} schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs className={"openapi-tabs__schema"}><TabItem label={"Schema"} value={"Schema"}><details style={{}} className={"openapi-markdown__details response"} data-collapsed={false} open={true}><summary style={{}} className={"openapi-markdown__details-summary-response"}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"errorCode"} required={true} schemaName={"integer"} qualifierMessage={undefined} schema={{"type":"integer","example":400}}></SchemaItem><SchemaItem collapsible={false} name={"errorDescription"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"Bad input parameter"}}></SchemaItem><SchemaItem collapsible={false} name={"errorKey"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"A text code of the refusal that does not change when the text changes. Only some refusals have it, for example `organisation_suspended`, `feature_disabled` or `purpose_exists`."}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"errorCode\": 400,\n  \"errorDescription\": \"Bad input parameter\",\n  \"errorKey\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"403"} value={"403"}><div>

The API key does not have the scope, or a token asks for another individual or is not allowed on this route.

</div><div><MimeTabs className={"openapi-tabs__mime"} schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs className={"openapi-tabs__schema"}><TabItem label={"Schema"} value={"Schema"}><details style={{}} className={"openapi-markdown__details response"} data-collapsed={false} open={true}><summary style={{}} className={"openapi-markdown__details-summary-response"}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><div><span className={"badge badge--info"}>anyOf</span><SchemaTabs><TabItem label={"MOD1"} value={"0-item-properties"}><SchemaItem collapsible={false} name={"errorCode"} required={true} schemaName={"integer"} qualifierMessage={undefined} schema={{"type":"integer","example":400}}></SchemaItem><SchemaItem collapsible={false} name={"errorDescription"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"Bad input parameter"}}></SchemaItem><SchemaItem collapsible={false} name={"errorKey"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"A text code of the refusal that does not change when the text changes. Only some refusals have it, for example `organisation_suspended`, `feature_disabled` or `purpose_exists`."}}></SchemaItem></TabItem><TabItem label={"Older error body"} value={"1-item-properties"}><SchemaItem collapsible={false} name={"Code"} required={true} schemaName={"integer"} qualifierMessage={undefined} schema={{"type":"integer","description":"The HTTP status.","example":403}}></SchemaItem><SchemaItem collapsible={false} name={"Message"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"What went wrong.","example":"Unauthorized access;User doesn't have enough permissions;"}}></SchemaItem></TabItem></SchemaTabs></div></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"500"} value={"500"}><div>

No individual has the mapper ID (`Failed to fetch individual by mapper id: <mapperId>`), or the server failed.

</div><div><MimeTabs className={"openapi-tabs__mime"} schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs className={"openapi-tabs__schema"}><TabItem label={"Schema"} value={"Schema"}><details style={{}} className={"openapi-markdown__details response"} data-collapsed={false} open={true}><summary style={{}} className={"openapi-markdown__details-summary-response"}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"errorCode"} required={true} schemaName={"integer"} qualifierMessage={undefined} schema={{"type":"integer","example":400}}></SchemaItem><SchemaItem collapsible={false} name={"errorDescription"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","example":"Bad input parameter"}}></SchemaItem><SchemaItem collapsible={false} name={"errorKey"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"A text code of the refusal that does not change when the text changes. Only some refusals have it, for example `organisation_suspended`, `feature_disabled` or `purpose_exists`."}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"errorCode\": 400,\n  \"errorDescription\": \"Bad input parameter\",\n  \"errorKey\": \"string\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div></div>