Business activities

Catalogue of business activities by country, required to obtain a valid activityCode when registering an organisation.

These endpoints act as a read-only catalogue for building the organisation registration request (see Registering a client organisation). The activityCode you send at registration must exist in this catalogue for the organisation's country; otherwise, registration responds with 404.

Common conventions

• Sandbox base URL: https://api-sandbox.zertiban.com
• Headers required on every call:
  • Authorization: Bearer {access_token}
  • x-tenant-id: {businessUuid}

1. List activity groups for a country

GET/business-activity/v1/business-activity-groups

Returns the activity-group tree for the given country, with the activities nested under each group. This is the natural shape for populating a selection dropdown.

Query parameters:

Parameter	Type	Required	Description
country	String	Yes	ISO 3166 alpha-2 code (e.g. "ES").

curl "https://api-sandbox.zertiban.com/business-activity/v1/business-activity-groups?country=ES" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "businessActivityGroups": [
    {
      "uuid": "b1a2c3d4-...",
      "code": "J",
      "description": "Information and communication",
      "businessActivities": [
        {
          "uuid": "e5f6a7b8-...",
          "code": "6201",
          "description": "Computer programming activities",
          "favourite": true
        },
        {
          "uuid": "c9d0e1f2-...",
          "code": "6202",
          "description": "Computer consultancy activities",
          "favourite": false
        }
      ]
    }
  ]
}

Field	Description
businessActivityGroups[i].code	Group code (high-level grouping).
businessActivityGroups[i].description	Group description, localised to the country.
businessActivities[j].code	Specific activity code. This is the value you send as activityCode.
businessActivities[j].favourite	Activities highlighted by Zertiban — useful for surfacing them at the top.

2. Look up a specific activity

GET/business-activity/v1/business-activities

Retrieves a specific activity by country and code. Use it when you already know the activityCode and want to validate that it exists or fetch its description and parent group.

Query parameters:

Parameter	Type	Required	Description
country	String	Yes	ISO 3166 alpha-2 code (e.g. "ES").
code	String	Yes	Activity code (e.g. "6201").

curl "https://api-sandbox.zertiban.com/business-activity/v1/business-activities?country=ES&code=6201" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "uuid": "e5f6a7b8-1234-4abc-9def-012345678901",
  "code": "6201",
  "description": "Computer programming activities",
  "favourite": true,
  "group": {
    "uuid": "b1a2c3d4-5678-4abc-9def-012345678901",
    "code": "J",
    "description": "Information and communication"
  }
}

3. Lookup by code (no country)

GET/business-activity/v1/business-activities/by-code/{code}

Returns the activity associated with the given code, resolving the country from the x-tenant-id header (the current organisation's country). Use it when you are already operating within an organisation's context and only need to resolve a code.

Path parameters:

Parameter	Type	Description
code	String	Activity code (2 digits, format ^[0-9]{2}$).

curl https://api-sandbox.zertiban.com/business-activity/v1/business-activities/by-code/20 \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "code": "20",
  "description": "Manufacture of pharmaceutical products"
}

Summary table

Method	Endpoint	Description
GET	/business-activity/v1/business-activity-groups?country={cc}	Country's activity-group tree
GET	/business-activity/v1/business-activities?country={cc}&code={code}	Specific activity by country and code
GET	/business-activity/v1/business-activities/by-code/{code}	Activity by code, using the tenant's country

Common errors

Code	Typical cause
400	country missing or code format invalid.
401	Expired token or invalid credentials.
403	Incorrect x-tenant-id or insufficient permissions.
404	No activity exists for the given (country, code) pair.