Job Titles

Overview

Job titles assigned to users indicate their job or position within the company. With this endpoint, users can be grouped into "pools" according to their job titles. A job title can also grant attributes or additional fields to users associated with it.

Get Job Titles

Returns all job titles within the company.

GET /jobtitles

Endpoint URL

https://www.cotalker.com/api/v2/jobtitles

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants access to the endpoint.	Required	true

Query Parameters

Parameter	Description	Type	Required	Notes
limit	Limits the amount of job titles returned in the response.	number	Optional	By default, the limit is set to 10.
page	Makes the response display data from the indicated page number.	number	Optional	Best used in combination with the "limit" parameter.
count	Adds the counter field with the total amount of job titles.	boolean	Optional
isActive	Returns job titles according to their jobtitles.active status.	string	Optional	Options are: all, true, false
ids	Returns job titles with the indicated ObjectIds in their jobtitles._id field.	ObjectId<COTJobTitle>[ ]	Optional
search	Returns job titles that match the keyword. Searches through the values of jobtitles.name, jobtitles.permissions, and jobtitles.description fields.	string	Optional	See COTJobTitle for data model details.
debug	Adds the debug field with error notifications and query values.	string	Optional	Option: true

Request Sample

cURL (default)

Request returns all job titles:

curl --location --request GET 'https://www.cotalker.com/api/v2/jobtitles' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

cURL (query)

Returns job titles that match search query along with a count of results:

curl --location --request GET 'https://www.cotalker.com/api/v2/jobtitles?search=chief&count=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

The response follows the COTJobTitle data model.

---

Get a Job Title by Id

Returns the job title indicated by the Id.

GET /jobtitles/{id}

Endpoint URL

https://www.cotalker.com/api/v2/jobtitles/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the job title that is to be returned.	ObjectId<COTJobTitle>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to view the job title.	Required	true

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v2/jobtitles/619648a6f27b4eb1a9e319ba' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

The response follows the COTJobTitle data model.

---

Create a Job Title

Creates a new job title within the company.

POST /jobtitles

Endpoint URL

https://www.cotalker.com/api/v2/jobtitles

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to create a job title.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTJobTitle data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
code	The job title's unique ID name	string	Required	Maximum 60 characters; only lowercase letters, numbers, and underscore allowed; must be unique.
display	The job title's display name	string	Required

Request Sample

Job title created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/jobtitles?debug=true' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": "senior_technical_writer",
    "display": "senior technical writer"
}'

Response Sample

Go to COTJobTitle for a complete description of the response.

{
    "_id": "61966da4ac5644318a6c77c6",
    "isActive": true,
    "allowedExtensions": [],
    "search": [
        "senior",
        "technical",
        "writer",
        "seniortechnicalwriter"
    ],
    "code": "senior_technical_writer",
    "display": "senior technical writer",
    "company": "61966d9b217c9eb47cb35f8d",
    "createdAt": "2021-11-18T14:07:35.519Z",
    "modifiedAt": "2021-11-18T14:07:35.520Z"
}

---

Update a Job Title

Updates or edits an existing job title.

PATCH /jobtitles/{id}

Endpoint URL

https://www.cotalker.com/api/v2/jobtitles/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the job title that is to be modified.	ObjectId<COTJobTitle>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to modify the job title.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTJobTitle data model.

Request Sample

curl --location --request PATCH 'https://www.cotalker.com/api/v2/jobtitles/61965e277c131a0007a6b111' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "allowedExtensions": [
        "6192276efd8ef0bfb1176b0a",
        "61922776ace7e2f9e5a9327a"
    ]
}'

Response Sample

Go to COTJobTitle for a complete description of the response.

{
    "_id": "61966da4ac5644318a6c77c6",
    "isActive": true,
    "allowedExtensions": [
        "6192276efd8ef0bfb1176b0a",
        "61922776ace7e2f9e5a9327a"
    ],
    "search": [
        "senior",
        "technical",
        "writer",
        "seniortechnicalwriter"
    ],
    "code": "senior_technical_writer",
    "display": "senior technical writer",
    "company": "61966d9b217c9eb47cb35f8d",
    "createdAt": "2021-11-18T14:07:35.519Z",
    "modifiedAt": "2021-11-18T15:09:52.623Z"
}

---