Vacancy

Vacancy represents a job opening in the Recrubo platform. Vacancies can be created and managed via the Recrubo platform, but also via the API.

Endpoints

• GET /vacancy - Retrieves a list of all vacancies.

• GET /vacancy/{id} - Retrieves a specific vacancy by ID.

• GET /vacancy/{id}?include=locations - Retrieves a specific vacancy by ID with all connected locations.

• POST /vacancy - Creates a new vacancy.

• PATCH /vacancy/{id} - Updates a specific vacancy by ID.

• DELETE /vacancy/{id} - Deletes a specific vacancy by ID.

Attributes

Field	Type	Description
title	String	The title for the vacancy. This will be shown in a list when a chatbot contains a vacancy selection.
description	String	The description of the vacancy. The AI can use this to respond to questions with knowledge of the specific vacancy.
deletedAt	DateTime	The date the vacancy was deleted.
url	String	The url of the job site where the vacancy is displayed.
externalId	String	The externalId is a field for external systems to store a tracking number.
createdAt	DateTime	The timestamp when the vacancy was created.
updatedAt	DateTime	The timestamp when the vacancy was last updated.

HTTP Methods

Field	GET	POST	PATCH
title	X	X	X
description	X	X	X
deletedAt	X
externalId	X	x	x
createdAt	X
updatedAt	X

Required Fields for Creation (POST)

Field	Type	Example value
title	String	Developer at Recrubo.
description	String	A vacancy description text containing detailed information about the vacancy.

Example POST body

{
  "data": {
    "type": "vacancies",
    "attributes": {
      "title": "Developer at Recrubo",
      "description": "A vacancy description text containing detailed information about the vacancy.",
      "url": "www.example.com/vacancies/developer-at-recrubo",
      "externalId": "1234"
    }
  }
}

Example PATCH body with locations

{
  "data": {
    "type": "vacancies",
    "attributes": {
      "title": "Developer at Recrubo",
      "description": "A vacancy description text containing detailed information about the vacancy.",
      "url": "www.example.com/vacancies/developer-at-recrubo",
      "externalId": "1234"
    },
    "relationships": {
      "locations": {
        "data": [
          { "type": "locations", "id": "2e23b4b4-4b4b-4b4b-4b4b-4b4b4b4b4b4b" },
          { "type": "locations", "id": "12345674-4b4b-4b4b-4b4b-4b4b4b4b4b4b" }
        ]
      }
    }
  }
}

OpenAPI

Create a Vacancy

post

Authorizations

Body

Responses

201

vacancy created

application/vnd.api+json

401

access denied

post

HTTPcURLJavaScriptPython

POST /public/v2/vacancies/ HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 159

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "title": "text",
      "description": "text",
      "deletedAt": "2025-06-06T17:39:41.281Z",
      "url": "text",
      "externalId": "text"
    }
  }
}

{
  "data": {
    "id": "29dcbd1e-1e61-4f63-b8c0-42ba47e350e0",
    "type": "vacancies",
    "attributes": {
      "createdAt": "2024-08-20T10:45:14+00:00",
      "updatedAt": "2024-08-20T10:45:14+00:00",
      "title": "Recrubo Back-end Deveoper",
      "description": "Ruby on Rails specialist",
      "deletedAt": null,
      "url": null,
      "externalId": null
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "/public/v2/organizations/1a558224-b12f-4280-89ac-354ff4e911f0"
        }
      },
      "user": {
        "links": {
          "related": null
        }
      },
      "vacancyCustomFields": {
        "links": {
          "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=29dcbd1e-1e61-4f63-b8c0-42ba47e350e0"
        }
      },
      "locations": {
        "links": {
          "related": "/public/v2/locations?filter[vacancyId]=29dcbd1e-1e61-4f63-b8c0-42ba47e350e0"
        }
      }
    }
  },
  "meta": {}
}

Retrieve all Vacancies

get

Authorizations

Responses

200

vacancies found

application/vnd.api+json

401

access denied

get

HTTPcURLJavaScriptPython

GET /public/v2/vacancies HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "b19fa26b-74f6-4f1b-a303-ce19f5722f80",
      "type": "vacancies",
      "attributes": {
        "createdAt": "2024-08-20T10:45:14+00:00",
        "updatedAt": "2024-08-20T10:45:14+00:00",
        "title": "Recrubo Back-end Deveoper",
        "description": "Ruby on Rails specialist",
        "deletedAt": null,
        "url": null,
        "externalId": null
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/public/v2/organizations/904c09a3-2110-47d5-9cb1-7eb617879b6c"
          }
        },
        "user": {
          "links": {
            "related": null
          }
        },
        "vacancyCustomFields": {
          "links": {
            "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=b19fa26b-74f6-4f1b-a303-ce19f5722f80"
          }
        },
        "locations": {
          "links": {
            "related": "/public/v2/locations?filter[vacancyId]=b19fa26b-74f6-4f1b-a303-ce19f5722f80"
          }
        }
      }
    },
    {
      "id": "523d3056-bdb9-4aa3-9ab1-ada17d59b35f",
      "type": "vacancies",
      "attributes": {
        "createdAt": "2024-08-20T10:45:14+00:00",
        "updatedAt": "2024-08-20T10:45:14+00:00",
        "title": "Recrubo Back-end Deveoper",
        "description": "Ruby on Rails specialist",
        "deletedAt": null,
        "url": null,
        "externalId": null
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/public/v2/organizations/904c09a3-2110-47d5-9cb1-7eb617879b6c"
          }
        },
        "user": {
          "links": {
            "related": null
          }
        },
        "vacancyCustomFields": {
          "links": {
            "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=523d3056-bdb9-4aa3-9ab1-ada17d59b35f"
          }
        },
        "locations": {
          "links": {
            "related": "/public/v2/locations?filter[vacancyId]=523d3056-bdb9-4aa3-9ab1-ada17d59b35f"
          }
        }
      }
    },
    {
      "id": "3b0d2e76-15fb-4ab4-8a8f-0c3ea8dfeabe",
      "type": "vacancies",
      "attributes": {
        "createdAt": "2024-08-20T10:45:14+00:00",
        "updatedAt": "2024-08-20T10:45:14+00:00",
        "title": "Recrubo Back-end Deveoper",
        "description": "Ruby on Rails specialist",
        "deletedAt": null,
        "url": null,
        "externalId": null
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/public/v2/organizations/904c09a3-2110-47d5-9cb1-7eb617879b6c"
          }
        },
        "user": {
          "links": {
            "related": null
          }
        },
        "vacancyCustomFields": {
          "links": {
            "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=3b0d2e76-15fb-4ab4-8a8f-0c3ea8dfeabe"
          }
        },
        "locations": {
          "links": {
            "related": "/public/v2/locations?filter[vacancyId]=3b0d2e76-15fb-4ab4-8a8f-0c3ea8dfeabe"
          }
        }
      }
    }
  ],
  "meta": {
    "total": 3,
    "totalUnfiltered": 3,
    "currentSize": 25,
    "currentPage": 1,
    "maxPage": 1
  }
}

Patch a Vacancy

patch

Authorizations

Path parameters

idstringRequired

Body

Responses

200

vacancy updated

application/vnd.api+json

401

access denied

404

Vacancy not found

patch

HTTPcURLJavaScriptPython

PATCH /public/v2/vacancies/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 159

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "title": "text",
      "description": "text",
      "deletedAt": "2025-06-06T17:39:41.281Z",
      "url": "text",
      "externalId": "text"
    }
  }
}

{
  "data": {
    "id": "0d466a12-bb7e-4e91-83e7-d74a2ea0ed82",
    "type": "vacancies",
    "attributes": {
      "createdAt": "2024-08-20T10:45:14+00:00",
      "updatedAt": "2024-08-20T10:45:14+00:00",
      "title": "New Title",
      "description": "And another description",
      "deletedAt": null,
      "url": null,
      "externalId": null
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "/public/v2/organizations/6292ab37-27f2-4c39-a184-ecf5daee9b95"
        }
      },
      "user": {
        "links": {
          "related": null
        }
      },
      "vacancyCustomFields": {
        "links": {
          "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=0d466a12-bb7e-4e91-83e7-d74a2ea0ed82"
        }
      },
      "locations": {
        "links": {
          "related": "/public/v2/locations?filter[vacancyId]=0d466a12-bb7e-4e91-83e7-d74a2ea0ed82"
        }
      }
    }
  },
  "meta": {}
}

Retrieve a single vacancy

get

Authorizations

Path parameters

idstringRequired

Responses

200

vacancy found

application/vnd.api+json

401

access denied

404

Vacancy not found

get

HTTPcURLJavaScriptPython

GET /public/v2/vacancies/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "ff3a67b7-d1c9-403a-9684-91d060bf3d62",
    "type": "vacancies",
    "attributes": {
      "createdAt": "2024-08-20T10:45:14+00:00",
      "updatedAt": "2024-08-20T10:45:14+00:00",
      "title": "Recrubo Back-end Deveoper",
      "description": "Ruby on Rails specialist",
      "deletedAt": null,
      "url": null,
      "externalId": null
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "/public/v2/organizations/9708d1a3-d168-4577-829d-a1a9ca410351"
        }
      },
      "user": {
        "links": {
          "related": null
        }
      },
      "vacancyCustomFields": {
        "links": {
          "related": "/public/v2/vacancy-custom-fields?filter[vacancyId]=ff3a67b7-d1c9-403a-9684-91d060bf3d62"
        }
      },
      "locations": {
        "links": {
          "related": "/public/v2/locations?filter[vacancyId]=ff3a67b7-d1c9-403a-9684-91d060bf3d62"
        }
      }
    }
  },
  "meta": {}
}

Destroy a Vacancy

delete

Authorizations

Path parameters

idstringRequired

Responses

204

vacancy destroyed

401

access denied

404

Vacancy not found

delete

HTTPcURLJavaScriptPython

DELETE /public/v2/vacancies/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

No content