New Empact Work

Reference

REST API reference

NewEmpact Integration API 2.0.0. Base URL https://api.newempactwork.com. Authenticate with Authorization: Bearer <integration_token>.

See also: authentication, quick start · 58 operations

All endpoints

Applicants

1 operation

GET /applicants List applicants applicants:read

Assignments

5 operations

GET /assignments List review assignments (optional status=`incomplete` for assigned|accepted|conflict) assignments:read DELETE /assignments/{assignmentId} Remove a review assignment assignments:write POST /assignments/{assignmentId}/reassign Move an existing assignment to a different reviewer assignments:write POST /assignments/auto Auto-assign reviewers using the programme’s assignment rules assignments:write POST /assignments/bulk Assign many submissions to reviewers in one request assignments:write

Audit

2 operations

GET /audit List audit log entries for the business audit:read GET /audit/{auditId} Fetch a single audit log entry by id audit:read

Email-sends

1 operation

GET /email-sends Look up outbound email sends by recipient address emails:read

Exports

2 operations

POST /exports Start an asynchronous integration export exports:write GET /exports/{exportId} Poll export job status; when completed, includes a short-lived downloadUrl for the JSON artifact exports:read

Feedback

2 operations

GET /feedback/released List feedback that has been released to applicants feedback:read POST /feedbacks/{feedbackId}/release Release a feedback record so the applicant can see it feedback:write

Files

1 operation

GET /files/{fileId}/download-url Generate a short-lived download URL for a file files:read

Payments

1 operation

GET /payments List payment records across submissions payments:read

Person-fields

1 operation

GET /person-fields/schema Get published person field schema person-fields:read

Persons

8 operations

GET /persons List persons persons:read POST /persons Create a person persons:write GET /persons/{personId} Get a person persons:read PATCH /persons/{personId} Update a person using optimistic locking persons:write DELETE /persons/{personId}/external-refs Remove a tenant-scoped external reference using optimistic locking persons:write POST /persons/{personId}/external-refs Add a tenant-scoped external reference using optimistic locking persons:write POST /persons/{personId}/merge Merge this source person into a canonical same-tenant target persons:write GET /persons/resolve Resolve persons persons:read

Programs

8 operations

GET /programs List programmes for the business programs:read GET /programs/{programId} Fetch a single programme by id programs:read PATCH /programs/{programId} Update programme name, description, year, dates, lifecycle status, or branding copy fields programs:write POST /programs/{programId}/bulk-email Send bulk email to selected reviewers and/or applicants in a programme emails:write GET /programs/{programId}/rounds List review rounds within a programme rounds:read GET /programs/{programId}/tracks List tracks within a programme tracks:read PATCH /programs/{programId}/tracks/{trackId} Update track intake window/status and optional branding copy tracks:write PATCH /programs/{programId}/tracks/{trackId}/rounds/{roundId} Update round dates and active flag rounds:write

Reviewers

3 operations

GET /reviewers List reviewers reviewers:read GET /reviewers/{reviewerId} Get a reviewer reviewers:read POST /reviewers/invite Invite a reviewer by email (creates membership + magic link) reviewers:write

Reviews

2 operations

GET /reviews List reviews (optional filters by submission, round, or reviewer) reviews:read GET /reviews/{reviewId} Fetch a single review by id reviews:read

Rubrics

1 operation

GET /rubrics/{rubricId} Fetch a review rubric by id (optional version; latest if omitted) rubrics:read

Schemas

1 operation

GET /schemas/{schemaId} Fetch an application schema by id (optional version; latest if omitted) schemas:read

Submissions

19 operations

GET /submissions List submissions for the business, with optional filters and pagination submissions:read POST /submissions Create an integration submission submissions:write GET /submissions/{submissionId} Fetch a single submission by id submissions:read PATCH /submissions/{submissionId} Update draft submission metadata, or change state (for example withdraw) submissions:write POST /submissions/{submissionId}/advance Advance a submission into a review round submissions:write POST /submissions/{submissionId}/eliminate Eliminate a submission from the programme submissions:write PATCH /submissions/{submissionId}/fields Update application field values on a submission submissions:write GET /submissions/{submissionId}/files List files attached to a submission files:read GET /submissions/{submissionId}/payment Get payment status for a submission (when the programme charges a fee) payments:read POST /submissions/{submissionId}/reopen Revert a submitted application back to draft so it can be edited again submissions:write GET /submissions/{submissionId}/reviews-summary Aggregate review scores and status for a submission reviews:read POST /submissions/{submissionId}/screen Mark a submission eligible or ineligible after screening submissions:write POST /submissions/{submissionId}/state Mark a submission as FINALIST or WINNER submissions:write POST /submissions/{submissionId}/submit Submit a draft application for review submissions:write GET /submissions/{submissionId}/supplements List supplement requests/responses for a submission supplements:read PATCH /submissions/{submissionId}/supplements/{supplementResponseId} Update a supplement response (answers or status fields allowed by the validator) supplements:write POST /submissions/{submissionId}/supplements/{supplementResponseId}/close Close a supplement response so it can no longer be edited supplements:write POST /submissions/{submissionId}/supplements/{supplementResponseId}/reopen Reopen a closed supplement response for further edits supplements:write POST /submissions/{submissionId}/withdraw Withdraw a submission from consideration submissions:write

Applicants

1 available call for this resource.

GET /applicants List applicants applicants:read
GET /applicants applicants:read

List applicants

Default response shape is unchanged. Set includePersonFieldIds to a comma-separated list of at most 25 IDs to add a person expansion. Expansion requires persons:read; requesting pii/restricted IDs also requires persons:sensitive:read. At most 100 rows are expanded, and missing or ambiguous Person matches retain the legacy applicant shape.

Parameters

NameInTypeDescription
programId query string optional
trackId query string optional
includePersonFieldIds query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Assignments

5 available calls for this resource.

GET /assignments List review assignments (optional status=`incomplete` for assigned|accepted|conflict) assignments:read DELETE /assignments/{assignmentId} Remove a review assignment assignments:write POST /assignments/{assignmentId}/reassign Move an existing assignment to a different reviewer assignments:write POST /assignments/auto Auto-assign reviewers using the programme’s assignment rules assignments:write POST /assignments/bulk Assign many submissions to reviewers in one request assignments:write
GET /assignments assignments:read

List review assignments (optional status=`incomplete` for assigned|accepted|conflict)

Parameters

NameInTypeDescription
programId query string optional
roundId query string optional
reviewerId query string optional
submissionId query string optional
status query string optional
includeInactive query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
DELETE /assignments/{assignmentId} assignments:write

Remove a review assignment

Parameters

NameInTypeDescription
assignmentId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /assignments/{assignmentId}/reassign assignments:write

Move an existing assignment to a different reviewer

Parameters

NameInTypeDescription
assignmentId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "newReviewerId",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "newReviewerId": {
      "type": "string",
      "minLength": 1
    },
    "reason": {
      "type": "string",
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /assignments/auto assignments:write

Auto-assign reviewers using the programme’s assignment rules

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "roundId"
  ],
  "additionalProperties": false,
  "properties": {
    "roundId": {
      "type": "string"
    },
    "reviewsPerSubmission": {
      "type": "integer",
      "minimum": 0
    },
    "useExpertiseMatching": {
      "type": "boolean"
    },
    "domainFieldId": {
      "type": "string",
      "maxLength": 100
    },
    "excludePriorRoundReviewers": {
      "type": "boolean"
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /assignments/bulk assignments:write

Assign many submissions to reviewers in one request

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "roundId"
  ],
  "additionalProperties": false,
  "properties": {
    "roundId": {
      "type": "string"
    },
    "submissionIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "reviewerIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "pairs": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "submissionId",
          "reviewerId"
        ],
        "additionalProperties": false,
        "properties": {
          "submissionId": {
            "type": "string"
          },
          "reviewerId": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Audit

2 available calls for this resource.

GET /audit List audit log entries for the business audit:read GET /audit/{auditId} Fetch a single audit log entry by id audit:read
GET /audit audit:read

List audit log entries for the business

Parameters

NameInTypeDescription
submissionId query string optional
programId query string optional
action query string optional
entityType query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /audit/{auditId} audit:read

Fetch a single audit log entry by id

Parameters

NameInTypeDescription
auditId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Email-sends

1 available call for this resource.

GET /email-sends Look up outbound email sends by recipient address emails:read
GET /email-sends emails:read

Look up outbound email sends by recipient address

Parameters

NameInTypeDescription
recipientEmail query string required
limit query integer optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Exports

2 available calls for this resource.

POST /exports Start an asynchronous integration export exports:write GET /exports/{exportId} Poll export job status; when completed, includes a short-lived downloadUrl for the JSON artifact exports:read
POST /exports exports:write

Start an asynchronous integration export

Default export request and output are unchanged. Set persons.fieldIds (maximum 25) to add an optional persons section. Person exports require persons:read; pii/restricted fields also require persons:sensitive:read. Resolution is bounded to 500 applicant/reviewer people per artifact and missing Person records are skipped.

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "programId"
  ],
  "additionalProperties": false,
  "properties": {
    "programId": {
      "type": "string"
    },
    "trackId": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "submittedFrom": {
      "type": "string",
      "format": "date-time"
    },
    "submittedTo": {
      "type": "string",
      "format": "date-time"
    },
    "persons": {
      "type": "object",
      "required": [
        "fieldIds"
      ],
      "additionalProperties": false,
      "properties": {
        "fieldIds": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          }
        }
      }
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /exports/{exportId} exports:read

Poll export job status; when completed, includes a short-lived downloadUrl for the JSON artifact

Parameters

NameInTypeDescription
exportId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Feedback

2 available calls for this resource.

GET /feedback/released List feedback that has been released to applicants feedback:read POST /feedbacks/{feedbackId}/release Release a feedback record so the applicant can see it feedback:write
GET /feedback/released feedback:read

List feedback that has been released to applicants

Parameters

NameInTypeDescription
programId query string optional
submissionId query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /feedbacks/{feedbackId}/release feedback:write

Release a feedback record so the applicant can see it

Parameters

NameInTypeDescription
feedbackId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Files

1 available call for this resource.

GET /files/{fileId}/download-url Generate a short-lived download URL for a file files:read
GET /files/{fileId}/download-url files:read

Generate a short-lived download URL for a file

Parameters

NameInTypeDescription
fileId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Payments

1 available call for this resource.

GET /payments List payment records across submissions payments:read
GET /payments payments:read

List payment records across submissions

Parameters

NameInTypeDescription
status query string required
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Person-fields

1 available call for this resource.

GET /person-fields/schema Get published person field schema person-fields:read
GET /person-fields/schema person-fields:read

Get published person field schema

Get the active published person custom-field schema.

Parameters

None

Responses

  • 200 Active published person custom-field schema.
    {
  "allOf": [
    {
      "type": "object",
      "required": [
        "success"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {},
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "details": {}
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "required": [
            "businessId",
            "entityType",
            "schemaVersion",
            "fields",
            "published",
            "publishedAt",
            "active",
            "createdBy",
            "createdAt",
            "updatedBy",
            "updatedAt",
            "version"
          ],
          "properties": {
            "businessId": {
              "type": "string"
            },
            "entityType": {
              "type": "string",
              "enum": [
                "person"
              ]
            },
            "schemaVersion": {
              "type": "integer",
              "minimum": 1
            },
            "sourceSchemaVersion": {
              "type": "integer",
              "minimum": 1
            },
            "fields": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "fieldId",
                  "key",
                  "label",
                  "type",
                  "required",
                  "sensitivity",
                  "archived",
                  "order"
                ],
                "additionalProperties": false,
                "properties": {
                  "fieldId": {
                    "type": "string",
                    "description": "Stable identifier used as the key in entity value maps."
                  },
                  "key": {
                    "type": "string",
                    "description": "Stable integration-facing key; immutable after creation.",
                    "pattern": "^[a-z][a-z0-9_]*$"
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "helpText": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "text",
                      "textarea",
                      "number",
                      "date",
                      "boolean",
                      "select",
                      "multiselect"
                    ]
                  },
                  "required": {
                    "type": "boolean"
                  },
                  "sensitivity": {
                    "type": "string",
                    "enum": [
                      "standard",
                      "pii",
                      "restricted"
                    ]
                  },
                  "constraints": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "min": {
                        "type": "number",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      "max": {
                        "type": "number",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      "minLength": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "maxLength": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 32768
                      },
                      "pattern": {
                        "type": "string"
                      },
                      "options": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 512
                        }
                      },
                      "minItems": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "maxItems": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      }
                    }
                  },
                  "defaultValue": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  },
                  "archived": {
                    "type": "boolean"
                  },
                  "order": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            },
            "published": {
              "type": "boolean"
            },
            "publishedAt": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "active": {
              "type": "boolean"
            },
            "createdBy": {
              "type": "string"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "updatedBy": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            },
            "version": {
              "type": "integer",
              "description": "Optimistic-lock version, distinct from schemaVersion.",
              "minimum": 0
            }
          }
        }
      }
    }
  ]
}

Persons

8 available calls for this resource.

GET /persons List persons persons:read POST /persons Create a person persons:write GET /persons/{personId} Get a person persons:read PATCH /persons/{personId} Update a person using optimistic locking persons:write DELETE /persons/{personId}/external-refs Remove a tenant-scoped external reference using optimistic locking persons:write POST /persons/{personId}/external-refs Add a tenant-scoped external reference using optimistic locking persons:write POST /persons/{personId}/merge Merge this source person into a canonical same-tenant target persons:write GET /persons/resolve Resolve persons persons:read
GET /persons persons:read

List persons

Cursor-paginated, tenant-scoped person list. Core identity, external IDs, metadata, and pii/restricted custom fields are omitted unless the token also has persons:sensitive:read.

Parameters

NameInTypeDescription
limit query integer optional
cursor query string optional
updatedAfter query string optional

Responses

  • 200 Redacted person page.
    {
  "allOf": [
    {
      "type": "object",
      "required": [
        "success"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {},
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "details": {}
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "Tenant-owned canonical person. Core contact fields, external IDs, metadata, and pii/restricted custom fields are omitted from standard reads.\n",
            "required": [
              "personId",
              "businessId",
              "kinds",
              "customFields",
              "customFieldSchemaVersion",
              "externalRefs",
              "provenance",
              "active",
              "anonymizedAt",
              "mergedIntoPersonId",
              "metadata",
              "createdBy",
              "createdAt",
              "updatedBy",
              "updatedAt",
              "version"
            ],
            "properties": {
              "personId": {
                "type": "string"
              },
              "businessId": {
                "type": "string"
              },
              "primaryEmail": {
                "type": "string",
                "format": "email"
              },
              "contactDetails": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "lastName": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 50
                  },
                  "organization": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              },
              "kinds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "applicant",
                    "reviewer",
                    "contact"
                  ]
                }
              },
              "platformUserId": {
                "type": "string"
              },
              "customFields": {
                "type": "object",
                "additionalProperties": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                }
              },
              "customFieldSchemaVersion": {
                "type": "integer",
                "minimum": 1
              },
              "externalRefs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "namespace",
                    "objectType"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "namespace": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255
                    },
                    "objectType": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255
                    },
                    "externalId": {
                      "type": "string",
                      "description": "Omitted unless the caller has person:sensitive_read.",
                      "minLength": 1,
                      "maxLength": 255
                    }
                  }
                }
              },
              "provenance": {
                "type": "object",
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "properties": {
                  "source": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "sourceId": {
                    "type": "string",
                    "maxLength": 255
                  }
                }
              },
              "active": {
                "type": "boolean"
              },
              "anonymizedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "mergedIntoPersonId": {
                "type": "string",
                "nullable": true
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              },
              "createdBy": {
                "type": "string"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedBy": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "version": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        },
        "meta": {
          "type": "object",
          "description": "Cursor pagination. Pass `lastEvaluatedKey` back as a query parameter to fetch the next page; `hasMore` is simply whether that cursor is present.\n",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string",
              "description": "Base64-encoded cursor."
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    }
  ]
}
POST /persons persons:write

Create a person

Create a tenant person independently of the legacy Person sync mode.

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "kinds",
    "provenance"
  ],
  "additionalProperties": false,
  "properties": {
    "primaryEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 255
    },
    "contactDetails": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "firstName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "phone": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        },
        "organization": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "address": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        }
      }
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "applicant",
          "reviewer",
          "contact"
        ]
      }
    },
    "platformUserId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "customFields": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 32768
          },
          {
            "type": "number",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          {
            "type": "boolean"
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 512
            },
            "maxItems": 100
          }
        ]
      }
    },
    "externalRefs": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "namespace",
          "objectType",
          "externalId"
        ],
        "additionalProperties": false,
        "properties": {
          "namespace": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "objectType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          }
        }
      }
    },
    "provenance": {
      "type": "object",
      "required": [
        "source"
      ],
      "additionalProperties": false,
      "properties": {
        "source": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "sourceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    }
  }
}

Responses

  • 201 Created person, redacted according to token scopes.
    {
  "allOf": [
    {
      "type": "object",
      "required": [
        "success"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {},
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "details": {}
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "description": "Tenant-owned canonical person. Core contact fields, external IDs, metadata, and pii/restricted custom fields are omitted from standard reads.\n",
          "required": [
            "personId",
            "businessId",
            "kinds",
            "customFields",
            "customFieldSchemaVersion",
            "externalRefs",
            "provenance",
            "active",
            "anonymizedAt",
            "mergedIntoPersonId",
            "metadata",
            "createdBy",
            "createdAt",
            "updatedBy",
            "updatedAt",
            "version"
          ],
          "properties": {
            "personId": {
              "type": "string"
            },
            "businessId": {
              "type": "string"
            },
            "primaryEmail": {
              "type": "string",
              "format": "email"
            },
            "contactDetails": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "firstName": {
                  "type": "string",
                  "maxLength": 100
                },
                "lastName": {
                  "type": "string",
                  "maxLength": 100
                },
                "phone": {
                  "type": "string",
                  "maxLength": 50
                },
                "organization": {
                  "type": "string",
                  "maxLength": 255
                },
                "title": {
                  "type": "string",
                  "maxLength": 255
                },
                "address": {
                  "type": "string",
                  "maxLength": 500
                }
              }
            },
            "kinds": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "applicant",
                  "reviewer",
                  "contact"
                ]
              }
            },
            "platformUserId": {
              "type": "string"
            },
            "customFields": {
              "type": "object",
              "additionalProperties": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              }
            },
            "customFieldSchemaVersion": {
              "type": "integer",
              "minimum": 1
            },
            "externalRefs": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "namespace",
                  "objectType"
                ],
                "additionalProperties": false,
                "properties": {
                  "namespace": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "objectType": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "externalId": {
                    "type": "string",
                    "description": "Omitted unless the caller has person:sensitive_read.",
                    "minLength": 1,
                    "maxLength": 255
                  }
                }
              }
            },
            "provenance": {
              "type": "object",
              "required": [
                "source"
              ],
              "additionalProperties": false,
              "properties": {
                "source": {
                  "type": "string",
                  "maxLength": 100
                },
                "sourceId": {
                  "type": "string",
                  "maxLength": 255
                }
              }
            },
            "active": {
              "type": "boolean"
            },
            "anonymizedAt": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "mergedIntoPersonId": {
              "type": "string",
              "nullable": true
            },
            "metadata": {
              "type": "object",
              "additionalProperties": true
            },
            "createdBy": {
              "type": "string"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "updatedBy": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            },
            "version": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    }
  ]
}
GET /persons/{personId} persons:read

Get a person

Get a canonical person by ID.

Parameters

NameInTypeDescription
personId path string required

Responses

  • 200 Canonical, scope-redacted person.
    {
  "allOf": [
    {
      "type": "object",
      "required": [
        "success"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {},
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "details": {}
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "description": "Tenant-owned canonical person. Core contact fields, external IDs, metadata, and pii/restricted custom fields are omitted from standard reads.\n",
          "required": [
            "personId",
            "businessId",
            "kinds",
            "customFields",
            "customFieldSchemaVersion",
            "externalRefs",
            "provenance",
            "active",
            "anonymizedAt",
            "mergedIntoPersonId",
            "metadata",
            "createdBy",
            "createdAt",
            "updatedBy",
            "updatedAt",
            "version"
          ],
          "properties": {
            "personId": {
              "type": "string"
            },
            "businessId": {
              "type": "string"
            },
            "primaryEmail": {
              "type": "string",
              "format": "email"
            },
            "contactDetails": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "firstName": {
                  "type": "string",
                  "maxLength": 100
                },
                "lastName": {
                  "type": "string",
                  "maxLength": 100
                },
                "phone": {
                  "type": "string",
                  "maxLength": 50
                },
                "organization": {
                  "type": "string",
                  "maxLength": 255
                },
                "title": {
                  "type": "string",
                  "maxLength": 255
                },
                "address": {
                  "type": "string",
                  "maxLength": 500
                }
              }
            },
            "kinds": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "applicant",
                  "reviewer",
                  "contact"
                ]
              }
            },
            "platformUserId": {
              "type": "string"
            },
            "customFields": {
              "type": "object",
              "additionalProperties": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              }
            },
            "customFieldSchemaVersion": {
              "type": "integer",
              "minimum": 1
            },
            "externalRefs": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "namespace",
                  "objectType"
                ],
                "additionalProperties": false,
                "properties": {
                  "namespace": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "objectType": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "externalId": {
                    "type": "string",
                    "description": "Omitted unless the caller has person:sensitive_read.",
                    "minLength": 1,
                    "maxLength": 255
                  }
                }
              }
            },
            "provenance": {
              "type": "object",
              "required": [
                "source"
              ],
              "additionalProperties": false,
              "properties": {
                "source": {
                  "type": "string",
                  "maxLength": 100
                },
                "sourceId": {
                  "type": "string",
                  "maxLength": 255
                }
              }
            },
            "active": {
              "type": "boolean"
            },
            "anonymizedAt": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "mergedIntoPersonId": {
              "type": "string",
              "nullable": true
            },
            "metadata": {
              "type": "object",
              "additionalProperties": true
            },
            "createdBy": {
              "type": "string"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "updatedBy": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            },
            "version": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    }
  ]
}
PATCH /persons/{personId} persons:write

Update a person using optimistic locking

Parameters

NameInTypeDescription
personId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "primaryEmail": {
      "type": "string",
      "format": "email",
      "maxLength": 255,
      "nullable": true
    },
    "contactDetails": {
      "type": "object",
      "nullable": true,
      "additionalProperties": false,
      "properties": {
        "firstName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "phone": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        },
        "organization": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "address": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        }
      }
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "applicant",
          "reviewer",
          "contact"
        ]
      }
    },
    "platformUserId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "nullable": true
    },
    "customFields": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 32768
          },
          {
            "type": "number",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          {
            "type": "boolean"
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 512
            },
            "maxItems": 100
          }
        ],
        "nullable": true
      }
    },
    "provenance": {
      "type": "object",
      "required": [
        "source"
      ],
      "additionalProperties": false,
      "properties": {
        "source": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "sourceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
DELETE /persons/{personId}/external-refs persons:write

Remove a tenant-scoped external reference using optimistic locking

Parameters

NameInTypeDescription
personId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "namespace",
    "objectType",
    "externalId",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "namespace": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "objectType": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /persons/{personId}/external-refs persons:write

Add a tenant-scoped external reference using optimistic locking

Parameters

NameInTypeDescription
personId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "externalRef",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "externalRef": {
      "type": "object",
      "required": [
        "namespace",
        "objectType",
        "externalId"
      ],
      "additionalProperties": false,
      "properties": {
        "namespace": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "objectType": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "externalId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /persons/{personId}/merge persons:write

Merge this source person into a canonical same-tenant target

Parameters

NameInTypeDescription
personId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "targetPersonId",
    "sourceVersion",
    "targetVersion"
  ],
  "additionalProperties": false,
  "properties": {
    "targetPersonId": {
      "type": "string"
    },
    "sourceVersion": {
      "type": "integer",
      "minimum": 0
    },
    "targetVersion": {
      "type": "integer",
      "minimum": 0
    },
    "preferSourceCustomFieldIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      }
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /persons/resolve persons:read

Resolve persons

Resolves exactly one personId, platformUserId, email, or complete external-reference selector. Email may return multiple active people. Sensitive values are scope-redacted.

Parameters

NameInTypeDescription
personId query string optional
email query string optional
platformUserId query string optional
namespace query string optional
objectType query string optional
externalId query string optional

Responses

  • 200 Active matching persons.
    {
  "allOf": [
    {
      "type": "object",
      "required": [
        "success"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {},
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "details": {}
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "lastEvaluatedKey": {
              "type": "string"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "Tenant-owned canonical person. Core contact fields, external IDs, metadata, and pii/restricted custom fields are omitted from standard reads.\n",
            "required": [
              "personId",
              "businessId",
              "kinds",
              "customFields",
              "customFieldSchemaVersion",
              "externalRefs",
              "provenance",
              "active",
              "anonymizedAt",
              "mergedIntoPersonId",
              "metadata",
              "createdBy",
              "createdAt",
              "updatedBy",
              "updatedAt",
              "version"
            ],
            "properties": {
              "personId": {
                "type": "string"
              },
              "businessId": {
                "type": "string"
              },
              "primaryEmail": {
                "type": "string",
                "format": "email"
              },
              "contactDetails": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "lastName": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 50
                  },
                  "organization": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              },
              "kinds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "applicant",
                    "reviewer",
                    "contact"
                  ]
                }
              },
              "platformUserId": {
                "type": "string"
              },
              "customFields": {
                "type": "object",
                "additionalProperties": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                }
              },
              "customFieldSchemaVersion": {
                "type": "integer",
                "minimum": 1
              },
              "externalRefs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "namespace",
                    "objectType"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "namespace": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255
                    },
                    "objectType": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255
                    },
                    "externalId": {
                      "type": "string",
                      "description": "Omitted unless the caller has person:sensitive_read.",
                      "minLength": 1,
                      "maxLength": 255
                    }
                  }
                }
              },
              "provenance": {
                "type": "object",
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "properties": {
                  "source": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "sourceId": {
                    "type": "string",
                    "maxLength": 255
                  }
                }
              },
              "active": {
                "type": "boolean"
              },
              "anonymizedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "mergedIntoPersonId": {
                "type": "string",
                "nullable": true
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              },
              "createdBy": {
                "type": "string"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedBy": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "version": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      }
    }
  ]
}

Programs

8 available calls for this resource.

GET /programs List programmes for the business programs:read GET /programs/{programId} Fetch a single programme by id programs:read PATCH /programs/{programId} Update programme name, description, year, dates, lifecycle status, or branding copy fields programs:write POST /programs/{programId}/bulk-email Send bulk email to selected reviewers and/or applicants in a programme emails:write GET /programs/{programId}/rounds List review rounds within a programme rounds:read GET /programs/{programId}/tracks List tracks within a programme tracks:read PATCH /programs/{programId}/tracks/{trackId} Update track intake window/status and optional branding copy tracks:write PATCH /programs/{programId}/tracks/{trackId}/rounds/{roundId} Update round dates and active flag rounds:write
GET /programs programs:read

List programmes for the business

Parameters

NameInTypeDescription
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /programs/{programId} programs:read

Fetch a single programme by id

Parameters

NameInTypeDescription
programId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /programs/{programId} programs:write

Update programme name, description, year, dates, lifecycle status, or branding copy fields

Parameters

NameInTypeDescription
programId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "year": {
      "type": "integer",
      "minimum": 1900,
      "maximum": 3000
    },
    "startDate": {
      "type": "string",
      "format": "date-time"
    },
    "endDate": {
      "type": "string",
      "format": "date-time"
    },
    "lifecycleStatus": {
      "type": "string",
      "enum": [
        "draft",
        "configured",
        "underway",
        "completed",
        "archived"
      ]
    },
    "branding": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "headerText": {
          "type": "string",
          "maxLength": 5000
        },
        "footerText": {
          "type": "string",
          "maxLength": 5000
        },
        "pages": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "landing": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "register": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "submission": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "submitted": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            }
          }
        }
      }
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /programs/{programId}/bulk-email emails:write

Send bulk email to selected reviewers and/or applicants in a programme

Parameters

NameInTypeDescription
programId path string required

Request body (required)

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "reviewers": {
      "type": "object",
      "required": [
        "reviewerIds",
        "subject",
        "body"
      ],
      "additionalProperties": false,
      "properties": {
        "reviewerIds": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "body": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50000
        }
      }
    },
    "applicants": {
      "type": "object",
      "required": [
        "applicantEmails",
        "subject",
        "body"
      ],
      "additionalProperties": false,
      "properties": {
        "applicantEmails": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        },
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "body": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50000
        }
      }
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /programs/{programId}/rounds rounds:read

List review rounds within a programme

Parameters

NameInTypeDescription
programId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /programs/{programId}/tracks tracks:read

List tracks within a programme

Parameters

NameInTypeDescription
programId path string required
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /programs/{programId}/tracks/{trackId} tracks:write

Update track intake window/status and optional branding copy

Parameters

NameInTypeDescription
trackId path string required
programId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "intakeOpen": {
      "type": "boolean"
    },
    "intakeOpenDate": {
      "type": "string",
      "format": "date-time"
    },
    "intakeCloseDate": {
      "type": "string",
      "format": "date-time"
    },
    "branding": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "headerText": {
          "type": "string",
          "maxLength": 5000
        },
        "footerText": {
          "type": "string",
          "maxLength": 5000
        },
        "pages": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "landing": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "register": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "submission": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            },
            "submitted": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "heroTitle": {
                  "type": "string",
                  "maxLength": 120
                },
                "heroSubtitle": {
                  "type": "string",
                  "maxLength": 240
                },
                "bodyHtml": {
                  "type": "string",
                  "maxLength": 5000
                },
                "ctaLabel": {
                  "type": "string",
                  "maxLength": 40
                }
              }
            }
          }
        }
      }
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /programs/{programId}/tracks/{trackId}/rounds/{roundId} rounds:write

Update round dates and active flag

Parameters

NameInTypeDescription
roundId path string required
trackId path string required
programId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "startDate": {
      "type": "string",
      "format": "date-time"
    },
    "endDate": {
      "type": "string",
      "format": "date-time"
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    },
    "active": {
      "type": "boolean"
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Reviewers

3 available calls for this resource.

GET /reviewers List reviewers reviewers:read GET /reviewers/{reviewerId} Get a reviewer reviewers:read POST /reviewers/invite Invite a reviewer by email (creates membership + magic link) reviewers:write
GET /reviewers reviewers:read

List reviewers

Default response shape is unchanged. Set includePersonFieldIds to a comma-separated list of at most 25 IDs to add a person expansion. Expansion requires persons:read; requesting pii/restricted IDs also requires persons:sensitive:read. At most 100 rows are expanded, and missing or ambiguous Person matches retain the legacy reviewer shape.

Parameters

NameInTypeDescription
programId query string optional
roundId query string optional
status query string optional
search query string optional
includePersonFieldIds query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /reviewers/{reviewerId} reviewers:read

Get a reviewer

Default response shape is unchanged. includePersonFieldIds follows the same person scope, sensitivity, and fallback rules as the reviewer list.

Parameters

NameInTypeDescription
reviewerId path string required
includePersonFieldIds query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /reviewers/invite reviewers:write

Invite a reviewer by email (creates membership + magic link)

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "lastName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "affiliation": {
      "type": "string",
      "maxLength": 200
    },
    "expertise": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      }
    },
    "roundIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "programName": {
      "type": "string",
      "maxLength": 200
    },
    "message": {
      "type": "string",
      "maxLength": 1000
    },
    "role": {
      "type": "string",
      "enum": [
        "reviewer",
        "lead_reviewer"
      ]
    },
    "suppressEmails": {
      "type": "boolean"
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Reviews

2 available calls for this resource.

GET /reviews List reviews (optional filters by submission, round, or reviewer) reviews:read GET /reviews/{reviewId} Fetch a single review by id reviews:read
GET /reviews reviews:read

List reviews (optional filters by submission, round, or reviewer)

Parameters

NameInTypeDescription
submissionId query string optional
roundId query string optional
reviewerId query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /reviews/{reviewId} reviews:read

Fetch a single review by id

Parameters

NameInTypeDescription
reviewId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Rubrics

1 available call for this resource.

GET /rubrics/{rubricId} Fetch a review rubric by id (optional version; latest if omitted) rubrics:read
GET /rubrics/{rubricId} rubrics:read

Fetch a review rubric by id (optional version; latest if omitted)

Parameters

NameInTypeDescription
rubricId path string required
version query integer optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Schemas

1 available call for this resource.

GET /schemas/{schemaId} Fetch an application schema by id (optional version; latest if omitted) schemas:read
GET /schemas/{schemaId} schemas:read

Fetch an application schema by id (optional version; latest if omitted)

Parameters

NameInTypeDescription
schemaId path string required
version query integer optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

Submissions

19 available calls for this resource.

GET /submissions List submissions for the business, with optional filters and pagination submissions:read POST /submissions Create an integration submission submissions:write GET /submissions/{submissionId} Fetch a single submission by id submissions:read PATCH /submissions/{submissionId} Update draft submission metadata, or change state (for example withdraw) submissions:write POST /submissions/{submissionId}/advance Advance a submission into a review round submissions:write POST /submissions/{submissionId}/eliminate Eliminate a submission from the programme submissions:write PATCH /submissions/{submissionId}/fields Update application field values on a submission submissions:write GET /submissions/{submissionId}/files List files attached to a submission files:read GET /submissions/{submissionId}/payment Get payment status for a submission (when the programme charges a fee) payments:read POST /submissions/{submissionId}/reopen Revert a submitted application back to draft so it can be edited again submissions:write GET /submissions/{submissionId}/reviews-summary Aggregate review scores and status for a submission reviews:read POST /submissions/{submissionId}/screen Mark a submission eligible or ineligible after screening submissions:write POST /submissions/{submissionId}/state Mark a submission as FINALIST or WINNER submissions:write POST /submissions/{submissionId}/submit Submit a draft application for review submissions:write GET /submissions/{submissionId}/supplements List supplement requests/responses for a submission supplements:read PATCH /submissions/{submissionId}/supplements/{supplementResponseId} Update a supplement response (answers or status fields allowed by the validator) supplements:write POST /submissions/{submissionId}/supplements/{supplementResponseId}/close Close a supplement response so it can no longer be edited supplements:write POST /submissions/{submissionId}/supplements/{supplementResponseId}/reopen Reopen a closed supplement response for further edits supplements:write POST /submissions/{submissionId}/withdraw Withdraw a submission from consideration submissions:write
GET /submissions submissions:read

List submissions for the business, with optional filters and pagination

Parameters

NameInTypeDescription
programId query string optional
trackId query string optional
state query string optional
roundId query string optional
submittedFrom query string optional
submittedTo query string optional
updatedSince query string optional
limit query integer optional
lastEvaluatedKey query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions submissions:write

Create an integration submission

The legacy innovatorId, innovatorEmail, and innovatorName payload remains supported. Alternatively supply exactly one personId or externalRef selector. Selectors require persons:read, resolve only an active same-tenant person, populate legacy identity and applicantPersonId server-side, and bypass legacy Person sync mode. Any legacy identity supplied alongside a selector must match the canonical Person.

Parameters

None

Request body (required)

{
  "type": "object",
  "required": [
    "trackId",
    "fields",
    "deadline"
  ],
  "additionalProperties": false,
  "properties": {
    "trackId": {
      "type": "string"
    },
    "fields": {
      "type": "object",
      "additionalProperties": {}
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    },
    "innovatorId": {
      "type": "string",
      "minLength": 1
    },
    "innovatorEmail": {
      "type": "string",
      "format": "email"
    },
    "innovatorName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "personId": {
      "type": "string"
    },
    "externalRef": {
      "type": "object",
      "required": [
        "namespace",
        "objectType",
        "externalId"
      ],
      "additionalProperties": false,
      "properties": {
        "namespace": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "objectType": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "externalId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /submissions/{submissionId} submissions:read

Fetch a single submission by id

Parameters

NameInTypeDescription
submissionId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /submissions/{submissionId} submissions:write

Update draft submission metadata, or change state (for example withdraw)

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "fields": {
      "type": "object",
      "additionalProperties": {}
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    },
    "state": {
      "type": "string",
      "enum": [
        "DRAFT",
        "WITHDRAWN"
      ]
    },
    "reason": {
      "type": "string",
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/advance submissions:write

Advance a submission into a review round

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "toRoundId",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "toRoundId": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/eliminate submissions:write

Eliminate a submission from the programme

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "reason",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /submissions/{submissionId}/fields submissions:write

Update application field values on a submission

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "fields",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "fields": {
      "type": "object",
      "additionalProperties": {}
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /submissions/{submissionId}/files files:read

List files attached to a submission

Parameters

NameInTypeDescription
submissionId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /submissions/{submissionId}/payment payments:read

Get payment status for a submission (when the programme charges a fee)

Parameters

NameInTypeDescription
submissionId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/reopen submissions:write

Revert a submitted application back to draft so it can be edited again

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "reason",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /submissions/{submissionId}/reviews-summary reviews:read

Aggregate review scores and status for a submission

Parameters

NameInTypeDescription
submissionId path string required
roundId query string optional

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/screen submissions:write

Mark a submission eligible or ineligible after screening

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "eligible",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "eligible": {
      "type": "boolean"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/state submissions:write

Mark a submission as FINALIST or WINNER

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "state",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "FINALIST",
        "WINNER"
      ]
    },
    "reason": {
      "type": "string",
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/submit submissions:write

Submit a draft application for review

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "minimum": 0
    },
    "acknowledgeSupplementWarnings": {
      "type": "boolean"
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
GET /submissions/{submissionId}/supplements supplements:read

List supplement requests/responses for a submission

Parameters

NameInTypeDescription
submissionId path string required

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
PATCH /submissions/{submissionId}/supplements/{supplementResponseId} supplements:write

Update a supplement response (answers or status fields allowed by the validator)

Parameters

NameInTypeDescription
supplementResponseId path string required
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "fields": {
      "type": "object",
      "additionalProperties": {}
    },
    "fileIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "not_started",
        "draft",
        "submitted",
        "closed"
      ]
    },
    "contributorId": {
      "type": "string"
    },
    "contributorIndex": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/supplements/{supplementResponseId}/close supplements:write

Close a supplement response so it can no longer be edited

Parameters

NameInTypeDescription
supplementResponseId path string required
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/supplements/{supplementResponseId}/reopen supplements:write

Reopen a closed supplement response for further edits

Parameters

NameInTypeDescription
supplementResponseId path string required
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}
POST /submissions/{submissionId}/withdraw submissions:write

Withdraw a submission from consideration

Parameters

NameInTypeDescription
submissionId path string required

Request body (required)

{
  "type": "object",
  "required": [
    "reason",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  }
}

Responses

  • 200 Success
    {
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {},
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "lastEvaluatedKey": {
          "type": "string"
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}