Report fields

How to populate each report field. Taxonomy and source values are ReliefWeb integer ids. Document and file url / uuid rules follow Trusted URLs and UUIDs. For PDF and image workflows (versions, PATCH merge, reorder), see Files and images.

Canonical schema: report.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 document UUID. Does not need to resolve to a live page. Never change it after first submission.

Example

"https://myorganization.org/report/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

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

Example

"c27c51bd-e6b6-5c09-91fd-ef122afdde8e"

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

Original title of the article or file. For series, add date or other distinguishing details as needed.

Example

"Example situation report for Country X"

Validation

  • Length 10–255 characters

  • Must contain letters

  • No leading, trailing, or consecutive spaces

source

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

Source organization ID(s) from /v2/sources (ReliefWeb integer taxonomy IDs, not UUIDs).

Example

[1503]

Validation

  • 1–30 unique integer IDs

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

country

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

Country ID(s) from /v2/countries. The first entry is the primary country. Tag only the most relevant.

Example

[13]

Validation

  • 1–300 unique integer IDs

  • First id is treated as the primary country

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

format

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

Single content-format ID from /v2/references/content-formats.

Example

[10]

Validation

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

  • Must be a valid content-formats reference id

language

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

Language ID(s) from /v2/references/languages. If an attachment is not in an official UN language, mention that in the attachment description.

Example

[267]

Validation

  • 1–10 unique integer IDs

  • Must be valid languages reference ids

published

Required yes
Type string (date-time)

Original publication date-time (ISO 8601) of the document.

Example

"2024-06-06T01:00:00+00:00"

Validation

  • ISO 8601 date-time

body

Required yes
Type string (markdown or HTML)

Full article text, or an executive summary when the main content is a PDF attachment. Markdown or a small set of HTML tags.

Example

"Short overview or full article text 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

embargoed

Required no
Type string (date-time)

UTC/GMT date-time until which the document stays embargoed; it publishes automatically at that time.

Example

"2024-06-06T07:00:00+00:00"

Validation

  • ISO 8601 date-time in UTC/GMT

origin

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

Optional real public page where readers can view the document. Unlike url, this should resolve to a live page.

Example

"https://myorganization.org/report/12345/view"

Validation

  • Valid IRI / URL

  • Max length 2048

  • Should be a real, accessible link when provided

file

Required no
Type object (UUID-keyed map)
Identifier UUID v5

PDF attachments keyed by permanent file UUID (max 10, 20MB each). Each value needs uuid, download_url, filename, checksum; url required on create. Use your organization domain for url; download_url may use a CDN. On PUT, the map replaces the whole attachment set; on PATCH, keys merge (null deletes that attachment).

Example

{
  "78d63e84-e2b4-5467-813d-1c2456f40d63": {
    "uuid": "78d63e84-e2b4-5467-813d-1c2456f40d63",
    "url": "https://myorganization.org/report/12345/attachment.pdf",
    "download_url": "https://myorganization.org/report/12345/attachment.pdf",
    "filename": "attachment.pdf",
    "checksum": "42fffa6c0e84ebab15f0f1ead8319efc448d0d883a0b492528997b4f17989755",
    "description": "First attachment",
    "language": "en"
  }
}

Validation

  • Map keyed by permanent file UUID (not a JSON array)

  • Max 10 attachments; max 20MB each

  • filename must end in lowercase .pdf

  • checksum is lowercase SHA-256 of the bytes at download_url

See also

file_order

Required no
Type array of UUID
Identifier UUID v5

Optional display order of attachment UUIDs. Unlisted attachments keep relative order at the end; unknown ids are ignored.

Example

["78d63e84-e2b4-5467-813d-1c2456f40d63"]

Validation

  • 1–10 unique UUIDs when present

  • Omit to preserve existing order (new attachments append)

See also

image

Required no
Type object
Identifier Trusted URL / IRI

Cover or illustration image. Required properties: download_url, checksum, description, copyright. No client-supplied uuid. Sending an image object replaces the whole cover; on PATCH, send "image": null to remove it.

Example

{
  "download_url": "https://myorganization.org/images/report-12345.png",
  "checksum": "c24863f6aa2065dd5071a831ee78439260ea72983799dd3e88fbfb4aa08fdc18",
  "description": "Test image",
  "copyright": "Test NGO"
}

Validation

  • download_url must end in .jpg, .png, or .webp (no query string)

  • checksum is lowercase SHA-256

  • Min width 700px; max file size 5MB

See also

disaster

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

Disaster ID(s) from /v2/disasters. Tag only the most relevant.

Example

[51754]

Validation

  • Optional; max 30 unique integer IDs

  • Must be valid /v2/disasters ids

disaster_type

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

Disaster-type ID(s) from /v2/references/disaster-types. Tag only the most relevant.

Example

[4628]

Validation

  • Optional; max 30 unique integer IDs

  • Must be valid disaster-types reference ids

theme

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

Theme ID(s) from /v2/references/themes. Tag only the most relevant.

Example

[4587,4595]

Validation

  • Optional; max 20 unique integer IDs

  • Must be valid themes reference ids

notify

Required no
Type array of string (email)

Email addresses to notify when the document is published.

Example

["editor@myorganization.org"]

Validation

  • Optional; max 10 email addresses

  • Each value must be a valid email

Next: Report examples