Use sparse fieldsets to limit the fields returned in API responses. This reduces payload size, speeds up responses, and minimizes exposure to personally identifiable information (PII).
- Performance: Smaller payloads result in faster API calls.
- Security: Avoid receiving unneeded sensitive fields.
- Clarity: Get only the data your app needs.
Sparse syntax overview
Sparse fieldsets are controlled via the fields[TYPE] query parameter. Use it to specify which attributes you want returned for each resource type.
# GET https://api.withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?fields[inquiry]=status
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved"
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "template",
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"attributes": {
"name": "Acme #1"
},
},
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"front-photo-url": "...",
"created-at": "2019-09-09T22:41:29.000Z",
"completed-at": "2019-09-09T22:41:40.000Z",
"...": "..."
},
},
{
"type": "verification/selfie",
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"attributes": {
"status": "passed",
"center-photo-url": "...",
"left-photo-url": "...",
"right-photo-url": "...",
"created-at": "2019-09-09T22:42:43.000Z",
"completed-at": "2019-09-09T22:42:46.000Z",
"...": "..."
},
}
],
"meta": {
"session-token": "..."
}
}You can also target nested fields inside the fields attribute:
# GET https://api.withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?fields[inquiry]=status,fields.name-first
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved",
"fields": {
"name-first": {
"type": "string",
"value": "Justin"
}
}
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "template",
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"attributes": {
"name": "Acme #1"
},
},
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"front-photo-url": "...",
"created-at": "2019-09-09T22:41:29.000Z",
"completed-at": "2019-09-09T22:41:40.000Z",
"...": "..."
},
},
{
"type": "verification/selfie",
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"attributes": {
"status": "passed",
"center-photo-url": "...",
"left-photo-url": "...",
"right-photo-url": "...",
"created-at": "2019-09-09T22:42:43.000Z",
"completed-at": "2019-09-09T22:42:46.000Z",
"...": "..."
},
}
],
"meta": {
"session-token": "..."
}
}You can also combine both attribute names and nested fields:
# GET https://api.withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?include=verifications&fields[verification/driver-license]=status,created-at
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved",
"reference-id": null,
"created-at": "2019-09-09T22:40:56.000Z",
"completed-at": "2019-09-09T22:44:51.000Z",
"expired-at": null,
"...": "...",
"fields": {
"name-first": {
"type": "string",
"value": "Justin"
},
"name-middle": {
"type": "string",
"value": null
},
"name-last": {
"type": "string",
"value": "Sayarath"
},
"address-street-1": {
"type": "string",
"value": "1 Main Street"
},
"address-street-2": {
"type": "string",
"value": null
},
"address-city": {
"type": "string",
"value": "San Francisco"
}
}
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"created-at": "2019-09-09T22:41:29.000Z"
},
}
],
"meta": {
"session-token": "..."
}
}Sparse fieldsets on included resources
You can apply sparse fieldsets to included resources as well. First, use the include parameter to pull in related resources. Then use fields[TYPE] to limit their attributes.
# GET https://api.withpersona.com/api/v1/inquiries/inq_2CVZ4HyVg7qaboXz2PUHknAn?include=verifications&fields[inquiry]=status&fields[verification/driver-license]=status,created-at
{
"data": {
"type": "inquiry",
"id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
"attributes": {
"status": "approved"
},
"relationships": {
"reports": {
"data": []
},
"sessions": {
"data": []
},
"template": {
"data": {
"id": "tmpl_JAZjHuAT738Q63BdgCuEJQre",
"type": "template"
}
},
"verifications": {
"data": [
{
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"type": "verification/driver-license"
},
{
"id": "ver_2aguhcwq66zcmqipmrqjxw68",
"type": "verification/selfie"
}
]
}
},
},
"included": [
{
"type": "verification/driver-license",
"id": "ver_KnqQRXmxmtquRE65CHTzymhR",
"attributes": {
"status": "passed",
"created-at": "2019-09-09T22:41:29.000Z"
},
}
],
"meta": {
"session-token": "..."
}
}Nested field names must match the structure in the API schema exactly. Use hyphenated keys where applicable.