API Documentation

API Endpoint

Custom Field Sections

Custom Field Section

CustomFieldSection is an entity that serves as a container for employee custom fields, enabling the grouping of those fields. Also in this way, employee custom fields cannot exist without belonging to a section. Each employee custom field belongs to a specific section and has section_id set, while one section contains several possible employee custom fields.

For more details on how to work with custom fields please refer to Working with custom fields guide.

Following diagram shows custom field sections in our data hierarchy:

CustomFieldSection diagram

Supported filter params

  • id

  • status (active: 1, archived: 2)

Supported sort params

  • id
GET /api/v2/custom_field_sections
Requestsreturns custom field sections

GET  /api/v2/custom_field_sections

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "1",
      "type": "custom_field_sections",
      "attributes": {
        "name": "custom field section",
        "description": "description",
        "position": 1
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "272"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "custom_field_sections",
      "attributes": {
        "name": "custom field section",
        "description": "description",
        "position": 1
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "272"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://api-test.productive.io/api/v2/custom_field_sections?page%5Bnumber%5D=1&page%5Bsize%5D=30",
    "last": "http://api-test.productive.io/api/v2/custom_field_sections?page%5Bnumber%5D=1&page%5Bsize%5D=30"
  },
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2,
    "page_size": 30,
    "max_page_size": 200
  }
}

Get custom field sections
GET/api/v2/custom_field_sections

GET /api/v2/custom_field_sections/1
Requestsreturns custom field section

GET  /api/v2/custom_field_sections/3

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "3",
    "type": "custom_field_sections",
    "attributes": {
      "name": "custom field section",
      "description": "description",
      "position": 1
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "273"
        }
      }
    }
  },
  "meta": {}
}

Gets the custom field section
GET/api/v2/custom_field_sections/{id}

URI Parameters
HideShow
id
number (required) Example: 1

custom field section id

POST /api/v2/custom_field_sections
Requestscreates the custom field section when params are validreturns error when params are invalid

POST  /api/v2/custom_field_sections

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "custom_field_sections",
    "attributes": {
      "name": "testing name",
      "description": "testing description",
      "position": 1
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "4",
    "type": "custom_field_sections",
    "attributes": {
      "name": "testing name",
      "description": "testing description",
      "position": 1
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "274"
        }
      }
    }
  },
  "meta": {}
}

POST  /api/v2/custom_field_sections

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "custom_field_sections",
    "attributes": {
      "name": null,
      "description": "testing description",
      "position": 1
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/name"
      }
    }
  ]
}

Creates the custom field section
POST/api/v2/custom_field_sections

URI Parameters
HideShow
name
string (required) Example: name

custom field section name

description
string (optional) Example: Some+description

description of the custom field section

position
number (optional) Example: 1

position of custom field section

PATCH /api/v2/custom_field_sections/1
Requestsupdates custom field section when params are validreturns error when params are invalid

PATCH  /api/v2/custom_field_sections/5

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "custom_field_sections",
    "attributes": {
      "name": "testing name",
      "description": "testing description",
      "position": 2
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "5",
    "type": "custom_field_sections",
    "attributes": {
      "name": "testing name",
      "description": "testing description",
      "position": 2
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "276"
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/custom_field_sections/6

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "custom_field_sections",
    "attributes": {
      "name": null,
      "description": "testing description",
      "position": 2
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/name"
      }
    }
  ]
}

Updates the custom field section
PATCH/api/v2/custom_field_sections/{id}

URI Parameters
HideShow
id
number (required) Example: 1

custom field section id

PATCH /api/v2/custom_field_sections/1/archive
Requestsarchives custom field section when it is not already archived and it does not contain any custom fieldsreturns error when custom field section is already archivedreturns error when custom field section contains employee custom fields

PATCH  /api/v2/custom_field_sections/7/archive

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "7",
    "type": "custom_field_sections",
    "attributes": {
      "name": "custom field section",
      "description": "description",
      "position": 1
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "278"
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/custom_field_sections/8/archive

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses409
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "409",
      "code": "record_already_archived",
      "title": "Conflict error",
      "source": {}
    }
  ]
}

PATCH  /api/v2/custom_field_sections/9/archive

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses409
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "409",
      "code": "record_contains_custom_fields",
      "title": "Conflict error",
      "source": {}
    }
  ]
}

Archives the custom field section
PATCH/api/v2/custom_field_sections/{id}/archive

URI Parameters
HideShow
id
number (required) Example: 1

custom field section id

Generated by aglio on 02 Aug 2025