API reference › Team › Schedulers

Create a new scheduler

POST /v1/scheduler

Scope
team:write
Roles
admin, scheduler

Creates a new scheduler

Parameters

None of its own.

Every call also sends Authorization and X-Tenant-ID; see Getting started.

Request body required

27 top-level fields; 5 hold nested fields, listed below.

FieldTypeDescription
name requiredstring

max length 255. Example Jordan Lee.

email requiredstring (email)

Unique among this organization's users.

max length 255. Example jordan@example.test.

jobRole requiredstring

Example Lead Scheduler.

status requiredobject (2 nested)
isPublishedboolean or null

Example true.

roleobject or null (2 nested)

The staff role the user holds: the Scheduler, one of the organization's custom roles (a role with is_custom true) or Admin. Portal roles are refused (422). Only an administrator can send the Admin role (403, code admin_role_forbidden). Left out, the user is a Scheduler.

rolesarray of object or null (3 nested)
descriptionstring or null

min length 5, max length 2000.

logostring (binary) or null

jpg, jpeg or png, max 2 MB.

countryCodestring or null

max length 5. Example +1.

phonestring or null

Required unless videoPhone is sent, and when receiveSms is true.

max length 20. Example 2025550101.

phoneTypestring or null

One of: sms_and_voice, voice_only.

phoneExtensionstring or null

max length 10.

videoPhoneCountryCodestring or null

max length 5. Example +1.

videoPhonestring or null

max length 20.

dateOfBirthstring (date) or null
genderobject or null (2 nested)

Required when the scheduler is published.

addressLine1string or null
addressLine2string or null
citystring or null
stateobject (2 nested)
postalCodestring or null

Example 78759.

receiveEmailboolean or null

Notification preference.

receiveSmsboolean or null

Notification preference.

receiveInAppboolean or null

Notification preference.

notifyOrgWideboolean or null

Receive notifications for every work item in the organization, not only the ones the scheduler owns.

defaultTimezonestring or null

Example America/Chicago.

Nested fields

status 2 fields
FieldTypeDescription
status.idinteger or string

Example 1.

status.labelstring or null

Example Example.

role 2 fields
FieldTypeDescription
role.idinteger

Example 7.

role.labelstring or null

Example Coordinator.

roles 3 fields
FieldTypeDescription
roles[].idinteger or null

Role id. Resolved from slug when omitted.

Example 3.

roles[].slugstring

Example consumer.

roles[].enabledboolean

Example true.

gender 2 fields
FieldTypeDescription
gender.idinteger or string

Example 1.

gender.labelstring or null

Example Example.

state 2 fields
FieldTypeDescription
state.idinteger or string

Example 1.

state.labelstring or null

Example Example.

Example

JSON
{
  "name": "Jordan Lee",
  "email": "jordan@example.test",
  "jobRole": "Lead Scheduler",
  "status": {
    "id": 1,
    "label": "Example"
  },
  "isPublished": true,
  "role": {
    "id": 7,
    "label": "Coordinator"
  },
  "roles": [
    {
      "id": 3,
      "slug": "consumer",
      "enabled": true
    }
  ],
  "description": "string",
  "logo": "string",
  "countryCode": "+1",
  "phone": "2025550101",
  "phoneType": "sms_and_voice",
  "phoneExtension": "string",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "string",
  "dateOfBirth": "string",
  "gender": {
    "id": 1,
    "label": "Example"
  },
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "state": {
    "id": 1,
    "label": "Example"
  },
  "postalCode": "78759",
  "receiveEmail": true,
  "receiveSms": true,
  "receiveInApp": true,
  "notifyOrgWide": true,
  "defaultTimezone": "America/Chicago"
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/scheduler" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jordan Lee","email":"jordan@example.test","jobRole":"Lead Scheduler","status":{"id":1,"label":"Example"},"isPublished":true,"role":{"id":7,"label":"Coordinator"},"roles":[{"id":3,"slug":"consumer","enabled":true}],"description":"string","logo":"string","countryCode":"+1","phone":"2025550101","phoneType":"sms_and_voice","phoneExtension":"string","videoPhoneCountryCode":"+1","videoPhone":"string","dateOfBirth":"string","gender":{"id":1,"label":"Example"},"addressLine1":"string","addressLine2":"string","city":"string","state":{"id":1,"label":"Example"},"postalCode":"78759","receiveEmail":true,"receiveSms":true,"receiveInApp":true,"notifyOrgWide":true,"defaultTimezone":"America/Chicago"}'

Try it

Responses

201 Scheduler created successfully

Scheduler created successfully

JSON
{
  "success": true,
  "message": "Scheduler created successfully",
  "data": {
    "id": "USR-ABC123"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Scheduler created successfully.

dataobject
data.idstring

Example USR-ABC123.

401 Not signed in

Unauthorized

JSON
{
  "success": false,
  "message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
  "errors": null,
  "code": "API_KEY_MISSING"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

Scope, tenant, IP allow-list or RBAC check failed.

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'team:write' scope.",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'team:write' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation error

JSON
{
  "success": false,
  "message": "The email you entered is already in use.",
  "errors": {
    "email": [
      "The email has already been taken."
    ]
  }
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

messagestring

Example The email you entered is already in use..

errorsobject
429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "success": false,
  "message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
  "errors": null,
  "code": "RATE_LIMITED"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.

500 Server error

Internal server error

JSON
{
  "success": false,
  "message": "An unexpected error occurred — please try again."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred — please try again..