Sparse Fieldsets#

Sparse fieldsets allow you to limit the number of attributes returned for a resource. Use the fields query parameter to request only the specific attributes you need, reducing payload size and improving performance.

This feature is especially useful when working with large or complex datasets, or when optimizing API responses for performance, bandwidth, or security. For example, you can:

  • Retrieve only specific status attributes (e.g., terminated or blocked) to monitor resource state.

  • Fetch minimal data when displaying resource lists or summaries.

  • Limit sensitive or unused fields in API integrations to control data exposure.

Tip

Combine sparse fieldsets with other query parameters such as filter or include to build efficient and highly targeted API requests.

This follows the JSON:API sparse fieldsets specification.

Note

Sparse fieldsets can be applied to any endpoint that returns a resource collection or a single resource object. Use this feature to retrieve only the most relevant fields for your application.



Retrieve a Single Attribute#

You can request a specific attribute by passing its name in the fields parameter.

In this example, the response for DIDs includes only the terminated attribute:

http

1GET /v3/dids?fields%5Bdids%5D=terminated HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]

curl

1curl -i -X GET 'https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"

response

 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
 8      "type": "dids",
 9      "attributes": {
10        "terminated": false
11      }
12    }
13  ],
14  "meta": {
15    "total_records": 1,
16    "api_version": "2026-11-19"
17  },
18  "links": {
19    "first": "https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated&page%5Bnumber%5D=1&page%5Bsize%5D=50",
20    "last": "https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated&page%5Bnumber%5D=1&page%5Bsize%5D=50"
21  }
22}

This is useful when you only need a single attribute from each resource, such as a DID’s termination state.



Retrieve Multiple Attributes#

To include more than one attribute, list them as comma-separated values within the fields parameter.

In this example, the response includes both terminated and blocked attributes:

http

1GET /v3/dids?fields%5Bdids%5D=terminated%2Cblocked HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]

curl

1curl -i -X GET 'https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated%2Cblocked' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"

response

 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
 8      "type": "dids",
 9      "attributes": {
10        "terminated": false,
11        "blocked": false
12      }
13    },
14    {
15      "id": "2c2a4cdd-5514-419f-abe2-2777d9b95533",
16      "type": "dids",
17      "attributes": {
18        "terminated": false,
19        "blocked": false
20      }
21    }
22  ],
23  "meta": {
24    "total_records": 2,
25    "api_version": "2026-11-19"
26  },
27  "links": {
28    "first": "https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated%2Cblocked&page%5Bnumber%5D=1&page%5Bsize%5D=50",
29    "last": "https://api.didww.com/v3/dids?fields%5Bdids%5D=terminated%2Cblocked&page%5Bnumber%5D=1&page%5Bsize%5D=50"
30  }
31}

This approach helps minimize unnecessary data transfer while retrieving key status attributes.



Apply Sparse Fieldsets to Multiple Resources#

When including related resources, you can define separate fields parameters for each type.

In this example, the request returns only selected attributes for both dids and their related did_group resources:

http

1GET /v3/dids?include=did_group&fields%5Bdids%5D=number%2Cterminated&fields%5Bdid_groups%5D=area_name HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]

curl

1curl -i -X GET 'https://api.didww.com/v3/dids?include=did_group&fields%5Bdids%5D=number%2Cterminated&fields%5Bdid_groups%5D=area_name' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"

response

 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
 8      "type": "dids",
 9      "attributes": {
10        "number": "12132211022",
11        "terminated": false
12      }
13    }
14  ],
15  "included": [
16    {
17      "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
18      "type": "did_groups",
19      "attributes": {
20        "area_name": "Los Angeles"
21      },
22      "meta": {
23        "available_dids_enabled": false,
24        "needs_registration": false,
25        "is_available": true,
26        "total_count": 7
27      }
28    }
29  ],
30  "meta": {
31    "total_records": 1,
32    "api_version": "2026-11-19"
33  },
34  "links": {
35    "first": "https://api.didww.com/v3/dids?fields%5Bdid_groups%5D=area_name&fields%5Bdids%5D=number%2Cterminated&include=did_group&page%5Bnumber%5D=1&page%5Bsize%5D=50",
36    "last": "https://api.didww.com/v3/dids?fields%5Bdid_groups%5D=area_name&fields%5Bdids%5D=number%2Cterminated&include=did_group&page%5Bnumber%5D=1&page%5Bsize%5D=50"
37  }
38}

This allows you to retrieve compact responses containing exactly the fields you need across related objects.