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

GET /v3/dids?fields%5Bdids%5D=terminated HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

curl

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

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
      "type": "dids",
      "attributes": {
        "terminated": false
      }
    }
  ],
  "meta": {
    "total_records": 1,
    "api_version": "2022-05-10"
  }
}

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

GET /v3/dids?fields%5Bdids%5D=terminated%2Cblocked HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

curl

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

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
      "type": "dids",
      "attributes": {
        "terminated": false,
        "blocked": false
      }
    },
    {
      "id": "2c2a4cdd-5514-419f-abe2-2777d9b95533",
      "type": "dids",
      "attributes": {
        "terminated": false,
        "blocked": false
      }
    }
  ],
  "meta": {
    "total_records": 2,
    "api_version": "2022-05-10"
  }
}

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

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

curl

curl -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 "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json"

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
      "type": "dids",
      "attributes": {
        "number": "12132211022",
        "terminated": false
      }
    }
  ],
  "included": [
    {
      "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
      "type": "did_groups",
      "attributes": {
        "area_name": "Los Angeles"
      }
    }
  ],
  "meta": {
    "total_records": 1,
    "api_version": "2022-05-10"
  }
}

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