Job fields

How to populate each job-posting field. Taxonomy and source values are ReliefWeb integer ids (look them up in the read API). Document url and uuid follow Trusted URLs and UUIDs.

Canonical schema: job.json.

url

Required yes
Type string (IRI / URL)
Identifier Trusted URL / IRI

Immutable unique identifier in URL form under your trusted document prefix. Used to generate the job UUID. Does not need to resolve to a live page. Never change after first submission.

Example

"https://myorganization.org/job/12345"

Validation

  • Must start with a trusted document prefix

  • Max length 2048

  • Never change after the first successful submission

See also

uuid

Required yes
Type string (UUID v5)
Identifier UUID v5

Job UUID v5 computed as uuid5(ReliefWeb namespace, url). Must match what the server computes from the exact url string.

Example

"efa7a5ff-a00c-500e-bc5d-d181874dc072"

Validation

  • Must be UUID format

  • Must equal uuid5('8e27a998-c362-5d1f-b152-d474e1d36af2', url)

  • Rejected if it does not match the server computation

See also

title

Required yes
Type string

Brief, specific job title. Prefer not to put location, salary, or other details in the title.

Example

"Example Humanitarian Affairs Officer"

Validation

  • Length 10–255 characters

  • Must contain letters

  • No leading, trailing, or consecutive spaces

  • No control characters (spaces allowed)

source

Required yes
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/sources — see docs

Single source organization ID from /v2/sources (ReliefWeb integer taxonomy ID, not a UUID).

Example

[1503]

Validation

  • Exactly one integer ID (minItems 1, maxItems 1)

  • Must be a valid /v2/sources id

closing_date

Required yes
Type string (date-time)

Application closing date-time (ISO 8601). Match your ad or careers portal.

Example

"2029-06-06T01:00:00+00:00"

Validation

  • ISO 8601 date-time

body

Required yes
Type string (markdown or HTML)

Full job description. Long enough to attract qualified candidates. Markdown or a small set of HTML tags.

Example

"Role overview and key responsibilities in markdown or HTML."

Validation

  • Length 10–100000 characters

  • Must contain letters

  • Allowed HTML tags: h1–h6, br, p, strong, em, a, ul, ol, li, blockquote

  • No leading/trailing/consecutive spaces (UNIX newlines allowed in body text)

how_to_apply

Required yes
Type string (markdown or HTML)

Short application instructions only. Do not repeat the job description.

Example

"Apply via the careers portal linked from the job URL."

Validation

  • Length 10–100000 characters

  • Must contain letters

  • Same HTML allowlist as body

  • Instructions only — not a second copy of the description

country

Required no
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/countries — see docs

Country ID(s) from /v2/countries. Omit for remote, roster/roving, or location TBD.

Example

[13]

Validation

  • Optional; max 10 unique integer IDs

  • Each value must be a valid /v2/countries id

  • Omit entirely when location is remote, roster/roving, or TBD

job_type

Required yes
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/references/job-types — see docs

Single job-type ID from /v2/references/job-types.

Example

[263]

Validation

  • At most one integer ID (maxItems 1)

  • Must be a valid job-types reference id

job_experience

Required yes
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/references/job-experience — see docs

Single job-experience ID from /v2/references/job-experience.

Example

[260]

Validation

  • At most one integer ID (maxItems 1)

  • Must be a valid job-experience reference id

career_category

Required yes
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/references/career-categories — see docs

Single career-category ID from /v2/references/career-categories.

Example

[36601]

Validation

  • At most one integer ID (maxItems 1)

  • Must be a valid career-categories reference id

theme

Required no
Type array of integer
Identifier ReliefWeb integer taxonomy ID (not a UUID)
Lookup /v2/references/themes — see docs

Single theme ID from /v2/references/themes. Choose only the most relevant.

Example

[4587]

Validation

  • Optional; at most one integer ID (maxItems 1)

  • Must be a valid themes reference id

Next: Job examples