API reference

This page is for the technical teams of organizations that want to connect their systems to the platform, such as an HR system that publishes opportunities by itself, or a student records system that verifies degrees. If you use the platform in a browser, you do not need it. It explains every operation the API offers: its address, what you send it and what it answers. The base address is ⁦/api/v1⁩; texts come in the language of the request. Connection keys are created in “Connect by API” on the organization's dashboard.

Version 1.2.0
Download the OpenAPI file

M1 Identity, accounts and organizations

Create an account, person, empty passport and consents

POST /api/v1/accounts

Permission (document 06): P-101
Open without signing in
On success: 201

Request fields
Field	Type	Required
`proof`	`string`	Yes
`name_ar`	`string`	Yes
`name_latin`	`string`	No
`governorate_code`	`string \| null`	No
`residence_country`	`string`	No
`password`	`string`	No
`preferred_language`	`ar \| en`	No
`accept_terms`	`boolean`	Yes
`consents`	`object[]`	No
`national_id`	`string`	No

Send a one-time code to a phone number

POST /api/v1/auth/otp

Permission (document 06): P-101
Open without signing in
On success: 202

Request fields
Field	Type	Required
`phone_e164`	`string`	Yes
`purpose`	`sign_up \| sign_in \| change_phone \| recovery`	Yes
`email`	`object`	No

Check a one-time code and return a short-lived proof

POST /api/v1/auth/otp/verify

Permission (document 06): P-101
Open without signing in
On success: 200

Request fields
Field	Type	Required
`phone_e164`	`string`	Yes
`purpose`	`sign_up \| sign_in \| change_phone \| recovery`	Yes
`email`	`object`	No
`code`	`string`	Yes

Start account recovery for a lost phone

POST /api/v1/auth/recovery

Permission (document 06): public
Open without signing in
On success: 201, 202

Request fields
Field	Type	Required
`old_phone_e164`	`string`	Yes
`proof`	`string`	Yes
`password`	`string`	No
`recovery_code`	`string`	No

Upload identity evidence for a manual recovery

POST /api/v1/auth/recovery/{case_id}/evidence

Permission (document 06): public
Open without signing in
On success: 202

Request fields
Field	Type	Required
`proof`	`string`	Yes
`file`	`string (uri)`	Yes

Sign in with phone and password or a code proof

POST /api/v1/auth/sessions

Permission (document 06): public
Open without signing in
On success: 201

Request fields
Field	Type	Required
`phone_e164`	`string`	No
`password`	`string`	No
`proof`	`string`	No

Sign out

DELETE /api/v1/auth/sessions/current

Permission (document 06): P-102
Needs a signed-in session
On success: 204

Takes no request body.

Give the second factor for this session (authenticator or recovery code)

POST /api/v1/auth/sessions/current/mfa

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`code`	`string`	Yes

Confirm the password or a code to the current number again before a sensitive change

POST /api/v1/auth/sessions/current/reauth

Permission (document 06): P-102
Needs a signed-in session
On success: 204

Request fields
Field	Type	Required
`password`	`string`	No
`proof`	`string`	No

The network of experts abroad

GET /api/v1/diaspora-network

Permission (document 06): P-601
Needs a signed-in session
On success: 200

Takes no request body.

Upload a file (quarantined until scanned)

POST /api/v1/files

Permission (document 06): P-201
Needs a signed-in session
On success: 202

Request fields
Field	Type	Required
`file`	`string (uri)`	Yes

The 14 governorates in the request language

GET /api/v1/governorates

Permission (document 06): public
Open without signing in
On success: 200

Takes no request body.

Own account, roles and memberships

GET /api/v1/me

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Takes no request body.

Switch the active role and organization

PUT /api/v1/me/active-role

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`role`	`string`	Yes
`org_id`	`string \| null (uuid)`	No

List own consents and their history

GET /api/v1/me/consents

Permission (document 06): P-103
Needs a signed-in session
On success: 200

Takes no request body.

Give or withdraw consent for a purpose

PUT /api/v1/me/consents/{purpose}

Permission (document 06): P-103
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`granted`	`boolean`	Yes

Request an export of own data (JSON and PDF)

POST /api/v1/me/data-exports

Permission (document 06): P-103
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`format`	`json \| pdf`	Yes

Delete own account after the grace period

POST /api/v1/me/deletion

Permission (document 06): P-103
Needs a signed-in session
On success: 202

Takes no request body.

What I offer from abroad

GET /api/v1/me/diaspora-offer

Permission (document 06): P-601
Needs a signed-in session
On success: 200

Takes no request body.

Offer expertise from abroad

PUT /api/v1/me/diaspora-offer

Permission (document 06): P-601
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`residence_country`	`string`	Yes
`offers`	`remote_work \| mentoring \| consulting \| volunteering \| return[]`	Yes
`fields`	`string[]`	No

Accept or refuse an invitation or an ownership offer

POST /api/v1/me/invitations/{membership_id}/decision

Permission (document 06): P-102
Needs a signed-in session
On success: 204

Request fields
Field	Type	Required
`accept`	`boolean`	Yes

Start an authenticator app: a new key, shown once

POST /api/v1/me/mfa/totp

Permission (document 06): P-102
Needs a signed-in session
On success: 201

Takes no request body.

Turn the authenticator app on with its first code; returns 10 recovery codes once

POST /api/v1/me/mfa/totp/confirm

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`code`	`string`	Yes

Change the phone number after a code to the new number

PUT /api/v1/me/phone

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`proof`	`string`	Yes

List own sessions and devices

GET /api/v1/me/sessions

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Takes no request body.

End every other session

DELETE /api/v1/me/sessions

Permission (document 06): P-102
Needs a signed-in session
On success: 204

Takes no request body.

End a session

DELETE /api/v1/me/sessions/{session_id}

Permission (document 06): P-102
Needs a signed-in session
On success: 204

Takes no request body.

Get an access token with client credentials

POST /api/v1/oauth/token

Permission (document 06): public
Open without signing in
On success: 200

Request fields
Field	Type	Required
`grant_type`	`client_credentials`	Yes
`client_id`	`string`	Yes
`client_secret`	`string`	Yes
`scope`	`string`	No

Register an organization (becomes pending approval)

POST /api/v1/organizations

Permission (document 06): P-104
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`org_type`	`company \| government \| ngo \| international \| issuer \| syndicate \| training_provider \| investor`	Yes
`legal_name`	`string`	Yes
`registration_no`	`string`	Yes
`sector_code`	`A \| B \| C \| D \| E \| F \| G \| H \| I \| J \| K \| L \| M \| N \| O \| P \| Q \| R \| S \| U`	Yes
`governorate_code`	`string`	Yes
`women_led`	`boolean`	No
`file_ids`	`string (uuid)[]`	Yes

Organization profile

GET /api/v1/organizations/{org_id}

Permission (document 06): P-105
Needs a signed-in session
On success: 200

Takes no request body.

Edit the organization profile and documents

PATCH /api/v1/organizations/{org_id}

Permission (document 06): P-105
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`org_type`	`company \| government \| ngo \| international \| issuer \| syndicate \| training_provider \| investor`	No
`legal_name`	`string`	No
`registration_no`	`string`	No
`sector_code`	`A \| B \| C \| D \| E \| F \| G \| H \| I \| J \| K \| L \| M \| N \| O \| P \| Q \| R \| S \| U`	No
`governorate_code`	`string`	No
`women_led`	`boolean`	No
`file_ids`	`string (uuid)[]`	No

List API clients

GET /api/v1/organizations/{org_id}/api-clients

Permission (document 06): P-110
Needs a signed-in session
On success: 200

Takes no request body.

Create an API client (secret shown once)

POST /api/v1/organizations/{org_id}/api-clients

Permission (document 06): P-110
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`name`	`string`	Yes
`scopes`	`opportunities:read \| opportunities:write \| applications:read \| applications:write \| verification:read \| verification:write \| verification:bulk[]`	Yes
`rate_limit_per_min`	`integer`	No

Revoke an API client

DELETE /api/v1/organizations/{org_id}/api-clients/{client_id}

Permission (document 06): P-110
Needs a signed-in session
On success: 204

Takes no request body.

Rotate the client secret

POST /api/v1/organizations/{org_id}/api-clients/{client_id}/rotation

Permission (document 06): P-110
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`overlap_hours`	`integer`	No

List members and their roles

GET /api/v1/organizations/{org_id}/members

Permission (document 06): P-106
Needs a signed-in session
On success: 200

Takes no request body.

Invite a member with a role

POST /api/v1/organizations/{org_id}/members

Permission (document 06): P-106
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`phone_e164`	`string`	Yes
`role`	`recruiter \| verifier \| viewer \| trainer \| analyst`	Yes

Change a member's role

PATCH /api/v1/organizations/{org_id}/members/{member_id}

Permission (document 06): P-106
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`role`	`recruiter \| verifier \| viewer \| trainer \| analyst`	No

Remove a member (ends sessions and keys)

DELETE /api/v1/organizations/{org_id}/members/{member_id}

Permission (document 06): P-106
Needs a signed-in session
On success: 204

Takes no request body.

Transfer ownership to another member

POST /api/v1/organizations/{org_id}/ownership-transfer

Permission (document 06): P-107
Needs a signed-in session
On success: 202

Request fields
Field	Type	Required
`member_id`	`string (uuid)`	Yes
`my_new_role`	`recruiter \| verifier \| viewer \| trainer \| analyst`	No

Production API clients waiting for approval

GET /api/v1/staff/api-clients

Permission (document 06): P-108
Needs a signed-in session
On success: 200

Takes no request body.

Approve or refuse a production API client

POST /api/v1/staff/api-clients/{client_id}/decision

Permission (document 06): P-108
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`approve`	`boolean`	Yes

Possible duplicate people and organizations

GET /api/v1/staff/duplicates

Permission (document 06): P-704
Needs a signed-in session
On success: 200

Takes no request body.

Merge or dismiss a possible duplicate

POST /api/v1/staff/duplicates/decisions

Permission (document 06): P-704
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`kind`	`person \| organization`	Yes
`kept_id`	`string (uuid)`	Yes
`other_id`	`string (uuid)`	Yes
`decision`	`merged \| dismissed`	Yes

Organizations waiting for approval

GET /api/v1/staff/organizations

Permission (document 06): P-108
Needs a signed-in session
On success: 200

Takes no request body.

Approve, reject, suspend or close an organization

POST /api/v1/staff/organizations/{org_id}/decision

Permission (document 06): P-108
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`decision`	`approve \| reject \| request_info \| suspend \| close`	Yes
`reason`	`string`	No
`record_types`	`qualification \| certificate \| training \| experience \| membership \| license[]`	No

Manual recovery queue

GET /api/v1/staff/recovery-cases

Permission (document 06): P-111
Needs a signed-in session
On success: 200

Takes no request body.

Approve or refuse a manual recovery

POST /api/v1/staff/recovery-cases/{case_id}/decision

Permission (document 06): P-111
Needs a signed-in session
On success: 204

Request fields
Field	Type	Required
`approve`	`boolean`	Yes
`reason`	`string`	Yes

Internal roles and who holds them

GET /api/v1/staff/role-grants

Permission (document 06): P-109
Needs a signed-in session
On success: 200

Takes no request body.

Grant an internal role

POST /api/v1/staff/role-grants

Permission (document 06): P-109
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`phone_e164`	`string`	Yes
`role`	`administrator \| content_editor \| curator \| expert_reviewer \| moderator`	Yes

Revoke an internal role

DELETE /api/v1/staff/role-grants/{grant_id}

Permission (document 06): P-109
Needs a signed-in session
On success: 204

Takes no request body.

applications

Confirm a hire; adds the job to the passport at L2

POST /api/v1/applications/{app_id}/hire-confirmation

Permission (document 06): P-308
Needs a signed-in session
On success: 201

Takes no request body.

catalog

Curated collections, drafts included

GET /api/v1/catalog/collections

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Create a curated collection

POST /api/v1/catalog/collections

Permission (document 06): P-504
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`title_ar`	`string`	Yes
`title_en`	`string`	Yes
`source_note`	`string`	Yes
`course_ids`	`string (uuid)[]`	No
`publish`	`boolean`	No

Edit or publish a curated collection

PATCH /api/v1/catalog/collections/{collection_id}

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`title_ar`	`string`	No
`title_en`	`string`	No
`source_note`	`string`	No
`course_ids`	`string (uuid)[]`	No
`publish`	`boolean`	No

Catalog courses in every state

GET /api/v1/catalog/courses

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Add a course to the catalog

POST /api/v1/catalog/courses

Permission (document 06): P-504
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`provider_id`	`string (uuid)`	No
`provider_course_id`	`string`	No
`title`	`string`	Yes
`language`	`ar \| en`	Yes
`delivery_mode`	`self_paced \| live_online \| in_person`	Yes
`fee_type`	`free \| paid \| subsidized \| grant_eligible`	Yes
`fee_amount`	`string \| null (decimal)`	No
`duration_hours`	`string \| null (decimal)`	No
`gives_certificate`	`boolean`	No
`enrollment_url`	`string \| null`	No
`skill_codes`	`string[]`	No
`status`	`imported \| published \| needs_update \| expired \| archived`	No
`confirm`	`boolean`	No

One catalog course

GET /api/v1/catalog/courses/{course_id}

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Edit a course

PATCH /api/v1/catalog/courses/{course_id}

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`provider_id`	`string (uuid)`	No
`provider_course_id`	`string`	No
`title`	`string`	No
`language`	`ar \| en`	No
`delivery_mode`	`self_paced \| live_online \| in_person`	No
`fee_type`	`free \| paid \| subsidized \| grant_eligible`	No
`fee_amount`	`string \| null (decimal)`	No
`duration_hours`	`string \| null (decimal)`	No
`gives_certificate`	`boolean`	No
`enrollment_url`	`string \| null`	No
`skill_codes`	`string[]`	No
`status`	`imported \| published \| needs_update \| expired \| archived`	No
`confirm`	`boolean`	No

Import a provider's course file

POST /api/v1/catalog/imports

Permission (document 06): P-504
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`provider_id`	`string (uuid)`	Yes
`file`	`string (uri)`	Yes

A checked course file

GET /api/v1/catalog/imports/{import_id}

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Import the valid rows of a checked file

POST /api/v1/catalog/imports/{import_id}/confirmation

Permission (document 06): P-504
Needs a signed-in session
On success: 201

Takes no request body.

The error report of a course file (CSV)

GET /api/v1/catalog/imports/{import_id}/report

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Course providers

GET /api/v1/catalog/providers

Permission (document 06): P-504
Needs a signed-in session
On success: 200

Takes no request body.

Add a course provider

POST /api/v1/catalog/providers

Permission (document 06): P-504
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`name`	`string`	Yes
`accreditation_status`	`string`	No
`website`	`object`	No
`phone`	`string`	No

Sync a provider's courses by its API

POST /api/v1/catalog/providers/{provider_id}/sync

Permission (document 06): P-504
Needs a signed-in session
On success: 202

Takes no request body.

collections

Published curated collections

GET /api/v1/collections

Permission (document 06): P-502
Open without signing in
On success: 200

Takes no request body.

One published curated collection

GET /api/v1/collections/{collection_id}

Permission (document 06): P-502
Open without signing in
On success: 200

Takes no request body.

contracts

One contract with its milestones, deliveries and history

GET /api/v1/contracts/{contract_id}

Permission (document 06): P-404
Needs a signed-in session
On success: 200

Takes no request body.

Change the contract; the other party confirms it again

PATCH /api/v1/contracts/{contract_id}

Permission (document 06): P-404
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`scope`	`string`	No
`price`	`string (decimal)`	No
`currency`	`SYP \| USD`	No
`milestones`	`object[]`	No

Confirm a contract (active when both confirm)

POST /api/v1/contracts/{contract_id}/confirmation

Permission (document 06): P-404
Needs a signed-in session
On success: 201

Takes no request body.

Open a dispute

POST /api/v1/contracts/{contract_id}/disputes

Permission (document 06): P-406
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`statement`	`string`	Yes
`evidence_file_id`	`string \| null (uuid)`	No

Deliver a milestone

POST /api/v1/contracts/{contract_id}/milestones/{milestone_id}/deliveries

Permission (document 06): P-404
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`note`	`string`	No
`file_id`	`string \| null (uuid)`	No

Accept or return a delivery

POST /api/v1/contracts/{contract_id}/milestones/{milestone_id}/review

Permission (document 06): P-404
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`result`	`accepted \| changes_requested`	Yes
`comment`	`string`	No

Rate the other party after completion

POST /api/v1/contracts/{contract_id}/ratings

Permission (document 06): P-406
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`stars`	`integer`	Yes
`comment`	`string`	No

conversations

Own conversations

GET /api/v1/conversations

Permission (document 06): P-405
Needs a signed-in session
On success: 200

Takes no request body.

Start the conversation of a contract, an application or an offer

POST /api/v1/conversations

Permission (document 06): P-405
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`context_type`	`contract \| application \| offer`	Yes
`context_id`	`string (uuid)`	Yes

One conversation with its messages

GET /api/v1/conversations/{conversation_id}

Permission (document 06): P-405
Needs a signed-in session
On success: 200

Takes no request body.

Send a message

POST /api/v1/conversations/{conversation_id}/messages

Permission (document 06): P-405
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`body`	`string`	Yes

courses

Search the course catalog

GET /api/v1/courses

Permission (document 06): P-502
Open without signing in
On success: 200

Takes no request body.

One course with sessions and source

GET /api/v1/courses/{course_id}

Permission (document 06): P-502
Open without signing in
On success: 200

Takes no request body.

Count a visit to the provider, a question or a save

POST /api/v1/courses/{course_id}/actions

Permission (document 06): P-502
Open without signing in
On success: 202

Request fields
Field	Type	Required
`action`	`provider \| enquiry \| save`	Yes

Compare up to 4 courses

GET /api/v1/courses/comparison

Permission (document 06): P-502
Open without signing in
On success: 200

Takes no request body.

M2 Skills Passport and verification

Who viewed my profile

GET /api/v1/me/access-log

Permission (document 06): P-207
Needs a signed-in session
On success: 200

Takes no request body.

Generate a CV from the passport (Arabic or English PDF)

POST /api/v1/me/cv

Permission (document 06): P-205
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`language`	`ar \| en`	Yes
`template`	`classic \| band`	Yes
`sections`	`qualification \| certificate \| training \| experience \| skill \| language \| project \| volunteering \| membership \| license[]`	Yes
`exclude`	`string (uuid)[]`	No
`phone`	`boolean`	No
`city`	`boolean`	No

Import own education records after consent

POST /api/v1/me/education-imports

Permission (document 06): P-203
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`ministry`	`moe \| mohe`	Yes

Status of an import

GET /api/v1/me/education-imports/{import_id}

Permission (document 06): P-203
Needs a signed-in session
On success: 200

Takes no request body.

Keep or exclude the fetched education records

POST /api/v1/me/education-imports/{import_id}/confirmation

Permission (document 06): P-203
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`keep`	`integer[]`	Yes

Suggest an issuer that is not on the platform

POST /api/v1/me/issuer-suggestions

Permission (document 06): P-202
Needs a signed-in session
On success: 202

Request fields
Field	Type	Required
`name`	`string`	Yes
`section`	`qualification \| certificate \| training \| experience \| skill \| language \| project \| volunteering \| membership \| license`	Yes

Own passport with all records

GET /api/v1/me/passport

Permission (document 06): P-201
Needs a signed-in session
On success: 200

Takes no request body.

Add a record

POST /api/v1/me/passport/entries

Permission (document 06): P-201
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`occupation_code`	`string \| null`	No
`file_ids`	`string (uuid)[]`	No
`section`	`qualification \| certificate \| training \| experience \| skill \| language \| project \| volunteering \| membership \| license`	Yes
`data`	`object`	Yes

Edit a record (an L2 record becomes a new L0 version)

PATCH /api/v1/me/passport/entries/{entry_id}

Permission (document 06): P-201
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`occupation_code`	`string \| null`	No
`file_ids`	`string (uuid)[]`	No
`data`	`object`	No

Delete an unverified record

DELETE /api/v1/me/passport/entries/{entry_id}

Permission (document 06): P-201
Needs a signed-in session
On success: 204

Takes no request body.

Dispute or ask to correct a verified record

POST /api/v1/me/passport/entries/{entry_id}/disputes

Permission (document 06): P-208
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`reason`	`string`	Yes
`evidence_file_id`	`string \| null (uuid)`	No

Issuers that can verify the record, and what they would see

GET /api/v1/me/passport/entries/{entry_id}/verification-requests

Permission (document 06): P-202
Needs a signed-in session
On success: 200

Takes no request body.

Ask an issuer to verify a record

POST /api/v1/me/passport/entries/{entry_id}/verification-requests

Permission (document 06): P-202
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`issuer_org_id`	`string (uuid)`	Yes

Visibility of sections and fields

GET /api/v1/me/passport/visibility

Permission (document 06): P-204
Needs a signed-in session
On success: 200

Takes no request body.

Set visibility of sections and fields

PUT /api/v1/me/passport/visibility

Permission (document 06): P-204
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`sections`	`object`	No
`fields`	`object`	No

The passport as the public or an employer sees it

GET /api/v1/me/passport/visibility/preview

Permission (document 06): P-204
Needs a signed-in session
On success: 200

Takes no request body.

Records an issuer uploaded for me

GET /api/v1/me/pending-claims

Permission (document 06): P-201
Needs a signed-in session
On success: 200

Takes no request body.

Accept or reject a pending claim

POST /api/v1/me/pending-claims/{claim_id}/decision

Permission (document 06): P-201
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`accept`	`boolean`	Yes

The QR share link in force

GET /api/v1/me/share-links

Permission (document 06): P-205
Needs a signed-in session
On success: 200

Takes no request body.

Create a QR share link

POST /api/v1/me/share-links

Permission (document 06): P-205
Needs a signed-in session
On success: 201

Takes no request body.

Revoke a QR share link

DELETE /api/v1/me/share-links/{link_id}

Permission (document 06): P-205
Needs a signed-in session
On success: 204

Takes no request body.

Own work log

GET /api/v1/me/work-log

Permission (document 06): P-207
Needs a signed-in session
On success: 200

Takes no request body.

Upload a CSV of verified records

POST /api/v1/organizations/{org_id}/bulk-verifications

Permission (document 06): P-210
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`file`	`string (uri)`	Yes
`record_type`	`qualification \| certificate \| training \| experience \| skill \| language \| project \| volunteering \| membership \| license`	Yes

Batch status and counts

GET /api/v1/organizations/{org_id}/bulk-verifications/{batch_id}

Permission (document 06): P-210
Needs a signed-in session
On success: 200

Takes no request body.

Confirm the import of a checked file

POST /api/v1/organizations/{org_id}/bulk-verifications/{batch_id}/confirmation

Permission (document 06): P-210
Needs a signed-in session
On success: 202

Takes no request body.

Row errors as CSV

GET /api/v1/organizations/{org_id}/bulk-verifications/{batch_id}/errors

Permission (document 06): P-210
Needs a signed-in session
On success: 200

Takes no request body.

Issuer queue of record disputes

GET /api/v1/organizations/{org_id}/disputes

Permission (document 06): P-211
Needs a signed-in session
On success: 200

Takes no request body.

One dispute with the record and its history

GET /api/v1/organizations/{org_id}/disputes/{dispute_id}

Permission (document 06): P-211
Needs a signed-in session
On success: 200

Takes no request body.

Decide a dispute; correct or revoke a record

POST /api/v1/organizations/{org_id}/disputes/{dispute_id}/decision

Permission (document 06): P-211
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`outcome`	`verify \| uphold \| revoke`	Yes
`method`	`registry_check \| original_document \| direct_confirmation`	No
`note`	`string`	No
`data`	`object`	No

Issuer queue of verification requests

GET /api/v1/organizations/{org_id}/verification-requests

Permission (document 06): P-209
Needs a signed-in session
On success: 200

Takes no request body.

One request with the shared fields

GET /api/v1/organizations/{org_id}/verification-requests/{request_id}

Permission (document 06): P-209
Needs a signed-in session
On success: 200

Takes no request body.

Accept or reject a verification request

POST /api/v1/organizations/{org_id}/verification-requests/{request_id}/decision

Permission (document 06): P-209
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`decision`	`accept \| reject`	Yes
`method`	`registry_check \| original_document \| direct_confirmation`	No
`reason`	`not_found \| data_mismatch \| not_genuine \| other`	No
`note`	`string`	No
`valid_until`	`string (date)`	No

Records the issuer verified, found by the person's name

GET /api/v1/organizations/{org_id}/verified-records

Permission (document 06): P-211
Needs a signed-in session
On success: 200

Takes no request body.

Revoke a record the issuer verified

POST /api/v1/organizations/{org_id}/verified-records/{entry_id}/revocation

Permission (document 06): P-211
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`reason`	`string`	Yes

Open a shared passport by QR token

GET /api/v1/shared/{token}

Permission (document 06): P-206
Open without signing in
On success: 200

Takes no request body.

me

Own applications and their status

GET /api/v1/me/applications

Permission (document 06): P-303
Needs a signed-in session
On success: 200

Takes no request body.

One application with its history

GET /api/v1/me/applications/{app_id}

Permission (document 06): P-303
Needs a signed-in session
On success: 200

Takes no request body.

Withdraw an application

POST /api/v1/me/applications/{app_id}/withdrawal

Permission (document 06): P-303
Needs a signed-in session
On success: 201

Takes no request body.

Block an account

POST /api/v1/me/blocks

Permission (document 06): P-405
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`account_id`	`string (uuid)`	Yes

Unblock an account

DELETE /api/v1/me/blocks/{account_id}

Permission (document 06): P-405
Needs a signed-in session
On success: 204

Takes no request body.

Set career goals

PUT /api/v1/me/career-goals

Permission (document 06): P-501
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`occupation_code`	`string \| null`	Yes

Own contracts, as client or freelancer

GET /api/v1/me/contracts

Permission (document 06): P-404
Needs a signed-in session
On success: 200

Takes no request body.

The interest questionnaire, the answers so far and the goal

GET /api/v1/me/interest-profile

Permission (document 06): P-501
Needs a signed-in session
On success: 200

Takes no request body.

Save the interest questionnaire

PUT /api/v1/me/interest-profile

Permission (document 06): P-501
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`answers`	`object`	No
`personalization_on`	`boolean \| null`	No

Confirm an interview or ask for another time

POST /api/v1/me/interviews/{interview_id}/answer

Permission (document 06): P-303
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`confirm`	`boolean`	Yes
`note`	`string`	No

Own learning paths

GET /api/v1/me/learning-paths

Permission (document 06): P-503
Needs a signed-in session
On success: 200

Takes no request body.

Build a learning path for the career goal

POST /api/v1/me/learning-paths

Permission (document 06): P-503
Needs a signed-in session
On success: 201

Takes no request body.

Update progress of a step

PATCH /api/v1/me/learning-paths/{path_id}/activities/{step_id}

Permission (document 06): P-503
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`status`	`todo \| in_progress \| attended \| skipped \| mastered`	No

My mentoring requests, sent and received

GET /api/v1/me/mentoring-requests

Permission (document 06): P-601
Needs a signed-in session
On success: 200

Takes no request body.

Cases about my account or my organization's listings

GET /api/v1/me/moderation-cases

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Takes no request body.

One case as the reported party sees it

GET /api/v1/me/moderation-cases/{case_id}

Permission (document 06): P-102
Needs a signed-in session
On success: 200

Takes no request body.

Channel and frequency per category

GET /api/v1/me/notification-preferences

Permission (document 06): P-705
Needs a signed-in session
On success: 200

Takes no request body.

Change channel and frequency (security stays on)

PUT /api/v1/me/notification-preferences

Permission (document 06): P-705
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`preferences`	`object[]`	Yes

In-app notification list

GET /api/v1/me/notifications

Permission (document 06): P-705
Needs a signed-in session
On success: 200

Takes no request body.

Mark a notification read

POST /api/v1/me/notifications/{notification_id}/read

Permission (document 06): P-705
Needs a signed-in session
On success: 201

Takes no request body.

Own offers and what happened to them

GET /api/v1/me/offers

Permission (document 06): P-403
Needs a signed-in session
On success: 200

Takes no request body.

Invitations to apply that I received

GET /api/v1/me/opportunity-invitations

Permission (document 06): P-303
Needs a signed-in session
On success: 200

Takes no request body.

Accept or decline an invitation to apply

POST /api/v1/me/opportunity-invitations/{invitation_id}/decision

Permission (document 06): P-303
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`accept`	`boolean`	Yes

Career recommendations and skill gaps with explanations

GET /api/v1/me/recommendations

Permission (document 06): P-501
Needs a signed-in session
On success: 200

Takes no request body.

Mark a recommendation useful or not

POST /api/v1/me/recommendations/{rec_id}/feedback

Permission (document 06): P-501
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`useful`	`boolean`	Yes
`comment`	`string`	No

Saved opportunities and courses

GET /api/v1/me/saved-items

Permission (document 06): P-302
Needs a signed-in session
On success: 200

Takes no request body.

Save an opportunity or a course

POST /api/v1/me/saved-items

Permission (document 06): P-302
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`item_type`	`opportunity \| course`	Yes
`item_id`	`string (uuid)`	Yes

Remove a saved item

DELETE /api/v1/me/saved-items/{item_id}

Permission (document 06): P-302
Needs a signed-in session
On success: 204

Takes no request body.

List search alerts

GET /api/v1/me/search-alerts

Permission (document 06): P-302
Needs a signed-in session
On success: 200

Takes no request body.

Create a search alert

POST /api/v1/me/search-alerts

Permission (document 06): P-302
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`query`	`object`	Yes

Delete a search alert

DELETE /api/v1/me/search-alerts/{alert_id}

Permission (document 06): P-302
Needs a signed-in session
On success: 204

Takes no request body.

Own service card and the projects it may show

GET /api/v1/me/service-card

Permission (document 06): P-401
Needs a signed-in session
On success: 200

Takes no request body.

Publish or edit own service card

PUT /api/v1/me/service-card

Permission (document 06): P-401
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`title`	`string`	Yes
`category`	`design \| translation \| software \| engineering \| accounting \| teaching \| construction \| marketing \| writing \| other`	Yes
`price_min`	`string \| null (decimal)`	No
`price_max`	`string \| null (decimal)`	No
`currency`	`SYP \| USD`	No
`delivery_days`	`integer \| null`	No
`status`	`published \| hidden`	No
`portfolio`	`string (uuid)[]`	No

mentoring-requests

Request mentoring

POST /api/v1/mentoring-requests

Permission (document 06): P-601
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`mentor_id`	`string (uuid)`	Yes
`goal`	`string`	Yes
`time_zone`	`string`	Yes

Confirm that a mentoring session took place

POST /api/v1/mentoring-requests/{request_id}/confirmation

Permission (document 06): P-601
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`add_to_work_log`	`boolean`	No

Accept, decline or complete mentoring

POST /api/v1/mentoring-requests/{request_id}/decision

Permission (document 06): P-602
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`decision`	`accept \| decline \| complete`	Yes
`session_at`	`string (date-time)`	No
`time_zone`	`string`	No
`meeting_details`	`string`	No
`add_to_work_log`	`boolean`	No

moderation-cases

Appeal a moderation decision

POST /api/v1/moderation-cases/{case_id}/appeals

Permission (document 06): P-102
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`reason`	`string`	Yes

offers

Accept an offer; the others are declined

POST /api/v1/offers/{offer_id}/acceptance

Permission (document 06): P-404
Needs a signed-in session
On success: 201

Takes no request body.

opportunities

Search published opportunities

GET /api/v1/opportunities

Permission (document 06): P-301
Open without signing in
On success: 200

Takes no request body.

One published opportunity

GET /api/v1/opportunities/{opp_id}

Permission (document 06): P-301
Open without signing in
On success: 200

Takes no request body.

What applying shares, and what the passport does not show

GET /api/v1/opportunities/{opp_id}/application-preview

Permission (document 06): P-303
Needs a signed-in session
On success: 200

Takes no request body.

Apply with answers and files

POST /api/v1/opportunities/{opp_id}/applications

Permission (document 06): P-303
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`message`	`string`	No
`answers`	`object`	No
`file_ids`	`string (uuid)[]`	No

organizations

One application with the candidate passport view

GET /api/v1/organizations/{org_id}/applications/{app_id}

Permission (document 06): P-305
Needs a signed-in session
On success: 200

Takes no request body.

Schedule an interview

POST /api/v1/organizations/{org_id}/applications/{app_id}/interviews

Permission (document 06): P-306
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`scheduled_at`	`string (date-time)`	Yes
`time_zone`	`string`	Yes
`mode`	`in_person \| phone \| online`	Yes
`location_or_link`	`string \| null`	No

Move a candidate to the next stage

POST /api/v1/organizations/{org_id}/applications/{app_id}/transitions

Permission (document 06): P-305
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`action`	`shortlist \| interview \| offer \| hire \| reject`	Yes
`reason`	`string`	No

Reschedule or cancel an interview

PATCH /api/v1/organizations/{org_id}/interviews/{interview_id}

Permission (document 06): P-306
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`action`	`reschedule \| cancel`	No
`scheduled_at`	`string (date-time)`	No
`time_zone`	`string`	No
`mode`	`in_person \| phone \| online`	No
`location_or_link`	`string \| null`	No
`reason`	`string`	No

Invitations sent and their answers

GET /api/v1/organizations/{org_id}/invitations

Permission (document 06): P-307
Needs a signed-in session
On success: 200

Takes no request body.

Invite a person to apply

POST /api/v1/organizations/{org_id}/invitations

Permission (document 06): P-307
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`opportunity_id`	`string (uuid)`	Yes
`person_id`	`string (uuid)`	Yes

Organization's opportunities

GET /api/v1/organizations/{org_id}/opportunities

Permission (document 06): P-304
Needs a signed-in session
On success: 200

Takes no request body.

Create an opportunity (draft)

POST /api/v1/organizations/{org_id}/opportunities

Permission (document 06): P-304
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`opp_type`	`job \| internship \| training \| scholarship \| grant \| volunteering`	Yes
`title`	`string`	Yes
`description`	`string`	No
`occupation_code`	`string \| null`	No
`min_experience_years`	`integer \| null`	No
`education_level`	`object`	No
`languages`	`object[]`	No
`governorate_code`	`string \| null`	No
`is_remote`	`boolean`	No
`open_abroad`	`boolean`	No
`remote_from_abroad`	`boolean`	No
`tags`	`women_focused \| home_based \| flexible_hours \| digital[]`	No
`deadline`	`string (date)`	No
`eligibility`	`string`	No
`type_details`	`object \| null`	No
`skills`	`object[]`	No
`questions`	`object[]`	No

One of the organization's opportunities

GET /api/v1/organizations/{org_id}/opportunities/{opp_id}

Permission (document 06): P-304
Needs a signed-in session
On success: 200

Takes no request body.

Edit an opportunity

PATCH /api/v1/organizations/{org_id}/opportunities/{opp_id}

Permission (document 06): P-304
Needs a signed-in session
On success: 200

Request fields
Field	Type	Required
`opp_type`	`job \| internship \| training \| scholarship \| grant \| volunteering`	No
`title`	`string`	No
`description`	`string`	No
`occupation_code`	`string \| null`	No
`min_experience_years`	`integer \| null`	No
`education_level`	`object`	No
`languages`	`object[]`	No
`governorate_code`	`string \| null`	No
`is_remote`	`boolean`	No
`open_abroad`	`boolean`	No
`remote_from_abroad`	`boolean`	No
`tags`	`women_focused \| home_based \| flexible_hours \| digital[]`	No
`deadline`	`string (date)`	No
`eligibility`	`string`	No
`type_details`	`object \| null`	No
`skills`	`object[]`	No
`questions`	`object[]`	No

Applications for an opportunity

GET /api/v1/organizations/{org_id}/opportunities/{opp_id}/applications

Permission (document 06): P-305
Needs a signed-in session
On success: 200

Takes no request body.

Duplicate an opportunity

POST /api/v1/organizations/{org_id}/opportunities/{opp_id}/copies

Permission (document 06): P-304
Needs a signed-in session
On success: 201

Takes no request body.

Publish, pause, close or reopen

POST /api/v1/organizations/{org_id}/opportunities/{opp_id}/transitions

Permission (document 06): P-304
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`action`	`publish \| pause \| close`	Yes

Search the Reconstruction Experts Registry (logged)

GET /api/v1/organizations/{org_id}/reconstruction-experts

Permission (document 06): P-604
Needs a signed-in session
On success: 200

Takes no request body.

One expert of the registry, as employers see them (logged)

GET /api/v1/organizations/{org_id}/reconstruction-experts/{person_id}

Permission (document 06): P-604
Needs a signed-in session
On success: 200

Takes no request body.

Supply of verified professionals by occupation and governorate

GET /api/v1/organizations/{org_id}/reconstruction-supply

Permission (document 06): P-604
Needs a signed-in session
On success: 200

Takes no request body.

Search discoverable people (logged)

GET /api/v1/organizations/{org_id}/talent

Permission (document 06): P-307
Needs a signed-in session
On success: 200

Takes no request body.

One discoverable person's passport as employers see it (logged)

GET /api/v1/organizations/{org_id}/talent/{person_id}

Permission (document 06): P-307
Needs a signed-in session
On success: 200

Takes no request body.

reports

Report a listing, an account or a message

POST /api/v1/reports

Permission (document 06): P-309
Open without signing in
On success: 201

Request fields
Field	Type	Required
`target_type`	`opportunity \| account \| rating \| message`	Yes
`target_id`	`string (uuid)`	Yes
`reason`	`fraud \| discrimination \| misleading \| abuse \| other`	Yes
`details`	`string`	No
`evidence_file_id`	`string \| null (uuid)`	No

service-cards

Search freelancers' service cards

GET /api/v1/service-cards

Permission (document 06): P-301
Open without signing in
On success: 200

Takes no request body.

staff

Decide an appeal (different moderator)

POST /api/v1/staff/appeals/{appeal_id}/decision

Permission (document 06): P-702
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`action`	`remove \| restore \| suspend \| warn`	Yes
`reason`	`string`	Yes

Group effects found by the fairness audit

GET /api/v1/staff/fairness-reviews

Permission (document 06): P-906
Needs a signed-in session
On success: 200

Takes no request body.

Record the human review of a fairness finding

POST /api/v1/staff/fairness-reviews/{review_id}/decision

Permission (document 06): P-906
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`outcome`	`justified \| action_taken`	Yes
`note`	`string`	Yes

Open and appealed freelance disputes

GET /api/v1/staff/freelance-disputes

Permission (document 06): P-407
Needs a signed-in session
On success: 200

Takes no request body.

One dispute with the contract, messages and statements

GET /api/v1/staff/freelance-disputes/{dispute_id}

Permission (document 06): P-407
Needs a signed-in session
On success: 200

Takes no request body.

Decide a freelance dispute

POST /api/v1/staff/freelance-disputes/{dispute_id}/decision

Permission (document 06): P-407
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`action`	`restore \| close_contract \| remove_rating \| warn \| suspend`	Yes
`facts`	`string`	Yes
`reason`	`string`	Yes
`party`	`object`	No
`rating_id`	`string \| null (uuid)`	No

Escalate a failed call to the owner

POST /api/v1/staff/integration-calls/{call_id}/escalation

Permission (document 06): P-706
Needs a signed-in session
On success: 201

Takes no request body.

Retry a failed call with the same key

POST /api/v1/staff/integration-calls/{call_id}/retry

Permission (document 06): P-706
Needs a signed-in session
On success: 201

Takes no request body.

Status of every integration

GET /api/v1/staff/integrations

Permission (document 06): P-706
Needs a signed-in session
On success: 200

Takes no request body.

Moderation queue

GET /api/v1/staff/moderation-cases

Permission (document 06): P-701
Needs a signed-in session
On success: 200

Takes no request body.

One moderation case with its reports and evidence

GET /api/v1/staff/moderation-cases/{case_id}

Permission (document 06): P-701
Needs a signed-in session
On success: 200

Takes no request body.

Hide, restore, remove, warn or suspend

POST /api/v1/staff/moderation-cases/{case_id}/decisions

Permission (document 06): P-701
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`action`	`remove \| restore \| suspend \| warn`	Yes
`reason`	`string`	Yes

The register of sensitive fields

GET /api/v1/staff/sensitive-fields

Permission (document 06): P-704
Needs a signed-in session
On success: 200

Takes no request body.

Review a sensitive field

POST /api/v1/staff/sensitive-fields/{field_key}/review

Permission (document 06): P-704
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`purpose_ar`	`string`	No
`purpose_en`	`string`	No
`access_roles`	`string[]`	No
`optional`	`boolean`	No
`review_months`	`integer`	No

Add, map, merge, split or rename terms (new version)

POST /api/v1/staff/taxonomy/changes

Permission (document 06): P-704
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`notes`	`string`	No
`changes`	`object[]`	Yes

Suggested terms waiting for review, and the latest versions

GET /api/v1/staff/taxonomy/suggestions

Permission (document 06): P-704
Needs a signed-in session
On success: 200

Takes no request body.

taxonomy

Occupations with Arabic and English titles

GET /api/v1/taxonomy/occupations

Permission (document 06): P-301
Open without signing in
On success: 200

Takes no request body.

Skills with synonyms

GET /api/v1/taxonomy/skills

Permission (document 06): P-301
Open without signing in
On success: 200

Takes no request body.

Suggest a new skill or occupation term

POST /api/v1/taxonomy/suggestions

Permission (document 06): P-703
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`text`	`string`	Yes
`lang`	`ar \| en`	Yes

women-in-business

Women in Business section content and opportunities

GET /api/v1/women-in-business

Permission (document 06): P-603
Open without signing in
On success: 200

Takes no request body.

work-requests

Post a freelance work request as a client

POST /api/v1/work-requests

Permission (document 06): P-402
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`title`	`string`	Yes
`description`	`string`	Yes
`deliverables`	`string`	Yes
`budget_min`	`integer \| null`	No
`budget_max`	`integer \| null`	No
`currency`	`SYP \| USD`	No
`duration_days`	`integer`	Yes
`deadline`	`string (date)`	Yes
`is_remote`	`boolean`	No
`governorate_code`	`string \| null`	No

Offers on own work request, with each freelancer's profile

GET /api/v1/work-requests/{opp_id}/offers

Permission (document 06): P-402
Needs a signed-in session
On success: 200

Takes no request body.

Send an offer

POST /api/v1/work-requests/{opp_id}/offers

Permission (document 06): P-403
Needs a signed-in session
On success: 201

Request fields
Field	Type	Required
`price`	`string (decimal)`	Yes
`currency`	`SYP \| USD`	No
`timeline_days`	`integer`	Yes
`note`	`string`	No

Errors

Every error is problem details (RFC 9457) with the type application/problem+json. It always has these fields:

status: The HTTP status
code: A stable code for programs, such as code_invalid
title: A short title in the request language
detail: An explanation for the user in the request language (when there is one)
request_id: The ID of the request; quote it to support
errors: Field errors: a list of field and message

Changes

1.2.0, 3 November 2026

Success statuses follow section 2.2 of document 10: 202 for sending a code and for recovery evidence, 200 for checking a code, 204 for a recovery decision.
Field errors are a list of field and message.
This page: every operation with its permission, in Arabic and English.

1.1.0, 3 November 2026

Error codes are lower case; account_locked answers 429 with the wait in seconds.
Four new operations: governorates, second factor, re-authentication, confirming the authenticator app.
Every error carries request_id.

1.0.0, 29 October 2026

First approved version.