Invitations

When an invitation is created, Yardstik will invite the candidate to complete their report (by email and/or SMS depending on your settings). The invitation will include a link to the candidate's unique intake form. When the candidate accesses their form, the information they're required to enter will be defined by the package you chose when you created the invitation. For a broader explanation, see Order Your First Report.

Invitations have their own statuses that can be tracked using the GET operation.

Note: By default, invitations expire 7 days after they're created, but you can change that timeframe in your Notifications Settings. The changes you make will be applied to new invitations; they won't impact any existing ones.

List Invitations

Retrieve a paginated list of invitations. See Pagination.

SecurityApiKey
Request
query Parameters
order
string

Order listing results in ascending or descending order, when using order_by.
Accepted values are asc or desc. If not passed, defaults to ascending asc.

Examples:
order=desc
order_by
string

Order listing results by a specific property.

Examples:
order_by=created_at
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

query
string

Filter listing results by a specific property.

Examples:
query[created_at_gteq]=2022-01-01T00:00:00.000Z
Responses
200

List of invitations.

401

Unauthorized

404

Not Found

get/invitations
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create an invitation.
Creates a new invitation and emails the candidate asking them to complete a report.


SecurityApiKey 
Request 
Request Body schema: application/json
account_package_id
string <uuid> 
Account package ID you want to use for this invitation.  Use id from List Account Packages


 
candidate_id
string <uuid> 
ID of the candidate to invite.


 
expires_at
string <date-time> 
The date when the invitation should expire. If not provided, the expiration date will be calculated based on your account's notification settings.


 
Responses 
201
Invitation was created successfully.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


post/invitations
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "string",
  • "status": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "logo": "string",
  • "report_urls": [
    ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}
Get an invitation.
Retrieve an invitation with the given ID.


SecurityApiKey 
Request 
path Parameters
invitation_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The invitation ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Invitation details.


401
Unauthorized


404
Not Found


get/invitations/{invitation_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "status": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "logo": "string",
  • "report_urls": [
    ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}
Delete an invitation.
Permanently delete an invitation with the given ID.


SecurityApiKey 
Request 
path Parameters
invitation_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The invitation ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
204
No Content.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


delete/invitations/{invitation_id}
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
Cancel an invitation.
Cancel an invitation with the given ID..


SecurityApiKey 
Request 
path Parameters
invitation_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The invitation ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Invitation successfully canceled.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


patch/invitations/{invitation_id}/cancel
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "status": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "logo": "string",
  • "report_urls": [
    ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}
Refresh an invitation.
Refresh an invitation with the given invitation_id.
 Minimum expires_at date must be 24 hours in the future. There is no maximum.
 Can only refresh when the invitation is in expired or canceled status.


SecurityApiKey 
Request 
path Parameters
invitation_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The invitation ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
optional
expires_at
string <date-time> 
The date when the invitation should expire.  If not provided, the expiration date will be calculated based on your account's notification settings.


 
Responses 
200
Invitation successfully refreshed.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


patch/invitations/{invitation_id}/refresh
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "string",
  • "status": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "logo": "string",
  • "report_urls": [
    ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}
➔ Next to Reports