> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List professions
> List professions.
This API endpoint is in beta and may be subject to changes, including breaking changes (similarly to the legacy API endpoints), without prior notice. [Read more about versioning](/documentation/using-api/versioning).
**OAuth 2.0 scopes**
```
job-qualifications.readonly
```
or
```
job-qualifications.readwrite
```
## OpenAPI
````yaml /openapi-specs/lucca-api@2024-11-01.json get /lucca-api/professions
openapi: 3.1.0
info:
title: Lucca API reference
version: '2024-11-01'
description: Please refer to developers.luccasoftware.com.
contact:
name: API Support
url: https://www.luccasoftware.com
email: no-reply@luccasoftware.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{host}
description: Your Lucca account URL.
variables:
host:
default: example.ilucca.net
description: >-
The URL of your dedicated Lucca account: `{account}.{env}.{region}`.
Account reflects your company name. Env indicates the environment.
Region depends on your server location.
**Please, use your test or sandbox environments (and not your
production env.) for testing purposes.**
Environments:
- `ilucca`: production environment for customers.
- `ilucca-test`: test environment for customers.
- `ilucca-demo`: demo environment for prospects.
Regions:
- `.ch` for Swiss located accounts.
- `.net` for the others.
Regarding sandboxes, the pattern differs:
`https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`,
where:
- `{sandboxName}` is automatically generated upon creation.
- `{server}` may be "eu1", "eu2" or "ch1".
security: []
tags:
- name: organization
description: Organization.
- name: employees
description: Employees.
- name: employments
description: Employments & job-positions.
- name: employee-occupation-categories
description: Employee occupations categories.
- name: employee-job-qualifications
description: Job qualifications & professions.
- name: employee-attributes
description: Employee-Attributes.
- name: taxonomies
description: Taxonomies & taxonomy-labels.
- name: webhooks
description: Webhooks.
- name: working-time-arrangements
description: working-time-arrangements
- name: files
description: Files management.
paths:
/lucca-api/professions:
parameters:
- $ref: '#/components/parameters/api-version'
- $ref: '#/components/parameters/if-none-match'
- $ref: '#/components/parameters/if-match'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/include'
get:
tags:
- employee-job-qualifications
summary: List professions
description: List professions.
operationId: get-professions
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/is-archived'
responses:
'200':
description: OK
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Content-Encoding:
$ref: '#/components/headers/content-encoding'
ETag:
$ref: '#/components/headers/eTag'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/json:
schema:
unevaluatedProperties: false
allOf:
- $ref: '#/components/schemas/professions.read'
- description: A collection of profession resources.
examples:
professions:
$ref: '#/components/examples/professions.get.example'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
default:
$ref: '#/components/responses/500'
security:
- oAuth:
- job-qualifications.readonly
- oAuth:
- job-qualifications.readwrite
components:
parameters:
api-version:
name: Api-Version
in: header
description: Set the [API version](/documentation/using-api/versioning).
schema:
type: string
format: date
const: '2024-11-01'
enum:
- '2024-11-01'
maxLength: 10
examples:
- '2024-11-01'
required: true
if-none-match:
name: If-None-Match
in: header
description: >-
Only execute the request if current cached version of the resource does
not match the one given here.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
required: false
if-match:
name: If-Match
in: header
description: >-
Only execute the request if current cached version of the resource
matches the one given here. Useful to avoid concurrency conflicts.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
required: false
accept-encoding:
name: Accept-Encoding
description: List of compression algorithms you support.
in: header
schema:
type: string
examples:
unWeighted:
value: gzip, compress, br
weighted:
value: gzip;q=1.0, identity; q=0.5, *;q=0
include:
description: >-
Include metadata:
- `embedded`: the partial or complete representations of related resources
(e.g. the employee the resource belongs to).
- `links`: links to related resources or actions (e.g. approving a leave-request).
May be `null` when you do not have access to the resource (or action).
- `totalCount`: only applicable on collections (i.e. lists of resources), gives
the total number of items across all pages.
Read more about [expanding
responses](/documentation/using-api/includes).
name: include
in: query
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- embedded
- links
- totalCount
x-enumDescriptions:
embedded: >-
Partial or complete representations of related resources (e.g. the
employee the resource belongs to).
links: >-
Link resources to related resources or actions (e.g. approving a
leave-request).
May be `null` when you do not have access to the resource (or
action).
totalCount: >-
Is only applicable on collections (i.e. lists of resources), gives
the total number of items across all pages.
page:
name: page
in: query
description: >-
Cursor of the page to retrieve. Read more about
[pagination](/documentation/using-api/paging).
schema:
type: string
examples:
one:
summary: Page with token '!w.SDijk23'
value: '!w.SDijk23'
limit:
name: limit
in: query
description: |-
Number of items per page. Defaults to 25. Maximum is 100.
Read more about [pagination](/documentation/using-api/paging).
schema:
type: integer
default: 25
minimum: 0
maximum: 100
examples:
one:
summary: Retrieve 25 items.
value: 25
is-archived:
name: isArchived
description: |-
When omitted: return both archived and non-archived resources.
When `true`: only return archived resources.
When `false`: only return non-archived resources.
in: query
required: false
schema:
type: boolean
examples:
onlyArchived:
value: false
headers:
api-version:
description: Name (date of release) of the API version.
schema:
type: string
const: '2024-11-01'
examples:
- '2024-11-01'
maxLength: 10
required: true
content-encoding:
description: >-
HTTP representation header that lists the encodings and the order in
which they have been applied to the representation of the resource.
required: false
schema:
type: array
uniqueItems: true
items:
type: string
enum:
- gzip
- compress
- deflate
- br
examples:
gzip:
value:
- gzip
eTag:
description: Identifies the cached version of the resource.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
deprecation:
description: |
Signals the resource has been deprecated.
schema:
type: string
format: date
maxLength: 10
examples:
- '2024-01-01'
sunset:
description: >
The **Sunset** response header (see [RFC
8594](https://datatracker.ietf.org/doc/html/rfc8594)) indicates the
point in time at which this endpoint or resource will become
unavailable. The sunset value is a timestamp [RFC 9110 Section
5.6.7][rfc-9110-5.6.7] that usually points to the future. If a sunset
value points to the past, then the endpooint or resource must be
expected to become unavailable at any time.
As an API client, you should monitor the presence and value of all
**Sunset** headers and be ready to take counter measures.
schema:
type: string
format: date-time
examples:
- '2026-01-01T00:00:00Z'
schemas:
professions.read:
allOf:
- $ref: '#/components/schemas/professions'
- $ref: '#/components/schemas/profession.embedded'
professions:
title: professions
description: A collection of profession resources.
allOf:
- type: object
properties:
type:
type: string
const: professions
url:
type: string
format: uri
totalCount:
type:
- integer
- 'null'
format: int64
minimum: 0
description: >-
Total number of profession resources across all pages that
satisfy query parameters.
items:
type: array
minItems: 0
maxItems: 100
items:
$ref: '#/components/schemas/profession'
- $ref: '#/components/schemas/collection.links'
profession.embedded:
type: object
properties:
embedded:
description: >-
No embedded resources on a profession(s) response. Expect an empty
object if embedded are requested.
type:
- object
- 'null'
problem:
title: Problem
description: >-
Represents a "problem detail" as a way to carry machine-readable details
of errors in a HTTP response.
type: object
additionalProperties: true
properties:
type:
type:
- string
- 'null'
description: >-
Identifies the problem type. Points to a page containing a
human-readable documentation for the problem type.
example: https://tools.ietf.org/html/rfc7231#section-6.5.1
title:
type:
- string
- 'null'
description: 'A short, summary of the problem type (e.g.: Service Unavailable)'
example: Bad Request
status:
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem.
type:
- integer
- 'null'
format: int32
minimum: 100
maximum: 599
example: 400
detail:
description: >-
A human-readable explanation specific to this occurrence of the
problem.
type:
- string
- 'null'
example: One or more validation errors occurred.
errors:
type: object
additionalProperties:
type: array
items:
type: string
example:
startsOn:
- 'Invalid period: startsOn should be before endsOn.'
example:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
title: Bad Request
details: One or more validation errors occurred.
status: 400
errors:
startsOn:
- 'Invalid period: startsOn should be before endsOn.'
profession:
title: profession
description: >-
A profession represent a type of job practiced in the company. Examples
may be:
- Software engineering ;
- Consulting ;
- HR operations ;
- Finances ;
- Sales ;
- etc...
type: object
properties:
id:
type: string
minLength: 1
type:
type: string
const: profession
url:
type: string
format: uri
title:
description: >-
**Must be unique**. Leading and trailing spaces are automatically
removed.
type: string
minLength: 1
maxLength: 255
isArchived:
description: >-
Once archived, a profession can no longer be referenced by new
job-qualifications.
type: boolean
t9n:
type: object
additionalProperties: false
properties:
title:
$ref: '#/components/schemas/t9n'
links:
type: object
additionalProperties: false
example:
id: '89'
type: profession
url: https://example.ilucca.net/lucca-api/professions/89
title: Developer
isArchived: false
t9n:
title:
fr-FR: Développeur
links: {}
collection.links:
type: object
properties:
links:
title: Links
description: Links to related resources
type:
- object
- 'null'
required:
- prev
- next
properties:
prev:
allOf:
- $ref: '#/components/schemas/link'
- description: Link to the previous page. Is `null` on the first page.
next:
allOf:
- $ref: '#/components/schemas/link'
- description: Link to the next page. Is `null` on the last page.
t9n:
type:
- object
- 'null'
title: Translations
description: >-
Used for translation purposes. Object is structured as a dictionary
whose keys refer to translated properties of the parent object, and
whose values are a dictionary of supported languages.
On the parent object, the translated property value is considered the
"invariant" translation. It is expected to show this value whenever the
user's language has no translation in `t9n`.
Languages are identified through their RFC 4646 language tag.
properties:
de-DE:
description: German (Germany)
type:
- string
- 'null'
en-US:
description: English (United States of America)
type:
- string
- 'null'
en-GB:
description: English (Great Britain)
type:
- string
- 'null'
es-ES:
description: Spanish (Spain)
type:
- string
- 'null'
fr-FR:
description: French (France)
type:
- string
- 'null'
fr-CH:
description: French (Switzerland)
type:
- string
- 'null'
it-IT:
description: Italian (Italy)
type:
- string
- 'null'
nl-BE:
description: Dutch (Belgium)
type:
- string
- 'null'
nl-NL:
description: Dutch (Netherlands)
type:
- string
- 'null'
pt-PT:
description: Portuguese (Portugal)
type:
- string
- 'null'
link:
title: Link
description: Object that represents an hyperlink.
type:
- object
- 'null'
additionalProperties: false
properties:
href:
type: string
format: uri
description: URL to the related object.
required:
- href
examples:
professions.get.example:
summary: professions GET example
description: professions GET example
value:
type: professions
url: https://example.ilucca.net/lucca-api/professions?limit=25
totalCount: 29
items:
- id: '89'
type: profession
url: https://example.ilucca.net/lucca-api/professions/89
title: Developer
isArchived: false
t9n:
title:
fr-FR: Développeur
links: {}
links:
prev: null
next:
href: >-
https://example.ilucca.net/lucca-api/professions?page=!43df&limit=25
embedded: {}
responses:
'400':
description: |-
Bad request. You may:
- (write requests) make sure the request body conforms with the expected schema.
- double check all required parameters are set.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
title: One or more validation errors occurred.
status: 400
instance: https://example.ilucca.net/lucca-api/leaves/1573
errors:
endsOn:
- 'Invalid period: StartsOn should be before EndsOn.'
employeeId:
- The employeeId query parameter is required.
extensions:
traceId: '|78777424-49cc27e04281bbfc.'
'401':
description: You are not authenticated. Please refresh your token.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
type: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
title: Unauthorized
status: 401
instance: https://example.ilucca.net/lucca-api/employees/1573
'500':
description: Internal server error.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
title: Internal Server Error
status: 500
instance: https://example.ilucca.net/lucca-api/employees/1573
securitySchemes:
oAuth:
type: oauth2
description: >-
The Lucca API implements the [oAuth 2](https://oauth.net/2/) protocol
with the
[client-credentials-flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
Refer to RFC8725.
flows:
clientCredentials:
tokenUrl: https://accounts.world.luccasoftware.com/connect/token
scopes:
legal-entities.readonly: >-
Read
[legal-entities](/api-reference/latest/organization/legal-entity).
legal-entities.readwrite: >-
Create, update or delete
[legal-entities](/api-reference/latest/organization/legal-entity).
business-establishments.readonly: >-
Read
[business-establishments](/api-reference/latest/organization/business-establishment).
business-establishments.readwrite: >-
Create, update or delete
[business-establishments](/api-reference/latest/organization/business-establishment).
departments.readonly: Read [departments](/api-reference/latest/organization/department).
departments.readwrite: >-
Create, update or delete
[departments](/api-reference/latest/organization/department).
employees.readonly: Read [employees](/api-reference/latest/employees/employee).
employees.readwrite: >-
Create or update
[employees](/api-reference/latest/employees/employee).
employee-attribute-definitions.readonly: >-
Read
[employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
employee-attribute-definitions.readwrite: >-
Create, update or delete
[employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
employee-attributes.readonly: >-
Read
[employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
employee-attributes.readwrite: >-
Create, update or delete
[employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
employee-personal-records.readonly: >-
Read
[employee-personal-records](/api-reference/latest/employees/employee-personal-records).
This contains highly sensitive data about the personal detail of
the person.
employee-personal-records.readwrite: >-
Create, update or delete
[employee-personal-records](/api-reference/latest/employees/employee-personal-records).
This contains highly sensitive data about the personal detail of
the person.
employments.readonly: Read [employments](/api-reference/latest/employments/employment).
employments.readwrite: >-
Create, update or delete
[employments](/api-reference/latest/employments/employment).
employment-templates.readonly: >-
Read
[employment-templates](/api-reference/latest/employments/employment-template).
employment-templates.readwrite: >-
Create, update or archive
[employment-templates](/api-reference/latest/employments/employment-template).
job-positions.readonly: >-
Read
[job-positions](/api-reference/latest/employments/job-position).
job-positions.readwrite: >-
Create, update or delete
[job-positions](/api-reference/latest/employments/job-position).
probationary-periods.readonly: >-
Read
[probationary-periods](/api-reference/latest/employments/probationary-period).
probationary-periods.readwrite: >-
Create, update or delete
[probationary-periods](/api-reference/latest/employments/probationary-period).
occupation-categories.readonly: >-
Read
[occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
occupation-categories.readwrite: >-
Create, update or delete
[occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
job-qualifications.readonly: >-
Read
[job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
and
[professions](/api-reference/latest/employee-occupations/profession).
job-qualifications.readwrite: >-
Create, update or delete
[job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
and
[professions](/api-reference/latest/employee-occupations/profession).
taxonomies.readonly: >-
Read [taxonomies](/api-reference/latest/taxonomies/taxonomy) and
[taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
taxonomies.readwrite: >-
Create, update or delete
[taxonomies](/api-reference/latest/taxonomies/taxonomy) and
[taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
webhook-endpoints.readonly: Read webhook-endpoints.
webhook-endpoints.readwrite: Create and update webhook-endpoints.
webhook-deliveries.readonly: Read webhook-deliveries.
webhook-deliveries.readwrite: Send a ping event to a webhook-endpoint.
working-time-arrangements.readonly: Read working-time-arrangements.
files.readonly: Read files stored in Lucca.
files.readwrite: Upload a file to Lucca.
x-scope-metadata:
legal-entities.readonly:
criticality: low
resources: '[legal-entity](./organization/legal-entity)'
legal-entities.readwrite:
criticality: medium
resources: '[legal-entity](./organization/legal-entity)'
business-establishments.readonly:
criticality: low
resources: '[business-establishment](./organization/business-establishment)'
business-establishments.readwrite:
criticality: medium
resources: '[business-establishment](./organization/business-establishment)'
departments.readonly:
criticality: low
resources: '[department](./organization/department)'
departments.readwrite:
criticality: medium
resources: '[department](./organization/department)'
employees.readonly:
criticality: medium
resources: '[employee](./employees/employee)'
employees.readwrite:
criticality: medium
resources: '[employee](./employees/employee)'
employee-attribute-definitions.readonly:
criticality: low
resources: >-
[employee-attribute-definition](./employee-attributes/employee-attribute-definition)
employee-attribute-definitions.readwrite:
criticality: medium
resources: >-
[employee-attribute-definition](./employee-attributes/employee-attribute-definition)
employee-attributes.readonly:
criticality: medium
resources: '[employee-attribute](./employee-attributes/employee-attribute)'
employee-attributes.readwrite:
criticality: medium
resources: '[employee-attribute](./employee-attributes/employee-attribute)'
employee-personal-records.readonly:
criticality: high
resources: '[employee-personal-record](./employees/employee-personal-record)'
employee-personal-records.readwrite:
criticality: high
resources: '[employee-personal-record](./employees/employee-personal-record)'
employments.readonly:
criticality: medium
resources: '[employment](./employments/employment)'
employments.readwrite:
criticality: medium
resources: '[employment](./employments/employment)'
employment-templates.readonly:
criticality: medium
resources: '[employment-template](./employments/employment-template)'
employment-templates.readwrite:
criticality: medium
resources: '[employment-template](./employments/employment-template)'
job-positions.readonly:
criticality: low
resources: '[job-position](./employments/job-position)'
job-positions.readwrite:
criticality: medium
resources: '[job-position](./employments/job-position)'
probationary-periods.readonly:
criticality: medium
resources: '[probationary-period](./employments/probationary-period)'
probationary-periods.readwrite:
criticality: medium
resources: '[probationary-period](./employments/probationary-period)'
occupation-categories.readonly:
criticality: low
resources: >-
[occupation-category](./employee-occupation-categories/get-started)
occupation-categories.readwrite:
criticality: medium
resources: >-
[occupation-category](./employee-occupation-categories/get-started)
job-qualifications.readonly:
criticality: low
resources: >-
[job-qualification](./employee-job-qualifications/job-qualification)
and [professions](./employee-job-qualifications/profession)
job-qualifications.readwrite:
criticality: medium
resources: >-
[job-qualification](./employee-job-qualifications/job-qualification)
and [professions](./employee-job-qualifications/profession)
taxonomies.readonly:
criticality: low
resources: >-
[taxonomy](./taxonomies/taxonomy) &
[taxonomy-label](./taxonomies/taxonomy-label)
taxonomies.readwrite:
criticality: medium
resources: >-
[taxonomy](./taxonomies/taxonomy) &
[taxonomy-label](./taxonomies/taxonomy-label)
webhook-endpoints.readonly:
criticality: low
resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
webhook-endpoints.readwrite:
criticality: medium
resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
webhook-deliveries.readonly:
criticality: low
resources: >-
[webhook-delivery](./webhooks/webhook-delivery) &
[webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
webhook-deliveries.readwrite:
criticality: medium
resources: >-
[webhook-delivery](./webhooks/webhook-delivery) &
[webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
working-time-arrangements.readonly:
criticality: low
resources: >-
[working-time-arrangement](./working-time-arrangements/working-time-arrangement)
files.readonly:
criticality: medium
resources: '[file](./files/file)'
files.readwrite:
criticality: medium
resources: '[file](./files/file)'
````