Raytio APIs (0.3.0)

Download OpenAPI specification:Download

Cameron Beattie, Marc Loths et al: hello@rayt.io URL: https://www.rayt.io

The Raytio API allows users, organisations, profiles, profile objects, profile object permissions and relationships to be created, updated, read and deleted. It also provides identity document data extraction, data verification, credit checking, bank transaction and accounting data extraction

Authentication

bearerAuth

Use the identity_token from the /token endpoint

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT."

oauth

Allows Authentication for Raytio APIs

generateToken

To make API requests you will need an Authentication Token. Authentication Tokens are temporary "security codes" (similar to session cookies) that allow the system to identify who you are, and that you are allowed to do what you are requesting. For Authentication we use JSON Web Tokens (JWTs). JWTs need to be passed via an Authorization header to all of the Raytio endpoints. This token endpoint returns three types of authentication tokens. The identity_token must be passed as a Bearer token to the appropriate endpoint.
The refresh_token can be used to return updated identity_token and access_token values.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Username and Password details for authentication

grant_type
string
Enum:"refresh_token" "password"

The type of grant that is being requested

username
string
Value:"user@rayt.io"

User Name. Required where grant_type is password.

password
string
Value:"abcdefabcdef"

Password. Required where grant_type is password.

refresh_token
string

The refresh token. Required where grant_type is refresh_token.

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/token

Production server (uses live data)

https://api.rayt.io//oauth/{version}/token

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/token

Request samples

application/json
Copy
Expand all Collapse all
{
  • "grant_type": "refresh_token",
  • "username": "user@rayt.io",
  • "password": "abcdefabcdef",
  • "refresh_token": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "user@rayt.io has been authenticated.",
  • "identity_token": "abcdefabcdef",
  • "refresh_token": "abcdefabcdef",
  • "access_token": "abcdefabcdef"
}

addUser

The signup endpoint allows the creation of a new username and password. The user must be verified before it can be used.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Username and Password details for signup

username
required
string
Value:"user@rayt.io"

Username

password
required
string
Value:"abcdefabcdef"

Password

verification_code_org
string
Value:"abcd1234"

The verification code for the user being invited to the organisation. Only relevant if a non-existent user has been invited to join an existing organisation.

Responses

200

200 OK

400

Bad Request

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/signup

Production server (uses live data)

https://api.rayt.io//oauth/{version}/signup

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/signup

Request samples

application/json
Copy
Expand all Collapse all
{
  • "username": "user@rayt.io",
  • "password": "abcdefabcdef",
  • "verification_code_org": "abcd1234"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "User user@rayt.io has been created and an email with a verification code has been sent to the email address. Please confirm the verification code to complete the registration process."
}

verifyUser

The verify endpoint validates a user's email address by requiring that the code sent to that email address has been verified before the user is activated. The confirmation code expires within 24 hours of being generated. If the confirmation code is provided incorrectly then a new code will be generated and emailed to the user.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Username and Confirmation details for verify

username
required
string
Value:"user@rayt.io"

Username

verification_code
required
string
Value:"123456789"

Verification code as emailed to the user.

Responses

200

200 OK

400

Bad Request

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/verify

Production server (uses live data)

https://api.rayt.io//oauth/{version}/verify

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/verify

Request samples

application/json
Copy
Expand all Collapse all
{
  • "username": "user@rayt.io",
  • "verification_code": "123456789"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "User user@rayt.io is verified."
}

resetPassword

The password-reset endpoint will allow a user's password to be reset. A confirmation code will be emailed to the user which must then be provided, together with the new password, to the password-confirm endpoint. The confirmation code expires within 24 hours of being generated. Once a password reset request has been made, it will not be possible to authenticate until the new password has been confirmed.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Username details for password-reset

username
string
Value:"user@rayt.io"

Username

Responses

200

200 OK

400

Bad Request

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/password-reset

Production server (uses live data)

https://api.rayt.io//oauth/{version}/password-reset

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/password-reset

Request samples

application/json
Copy
Expand all Collapse all
{
  • "username": "user@rayt.io"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Password for user@rayt.io has been reset and an email with a verification code has been sent to the email address. Please confirm the verification code to reset the password."
}

confirmPassword

The password-confirm endpoint updates a user's password after a request has been made to password-reset. The confirmation code which has been emailed to the user must be provided, together with the new password.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Username details for password-confirm

username
string
Value:"user@rayt.io"

Username

verification_code
string
Value:"123456789"

Verification code as emailed to the user.

password
string
Value:"abcdefabcdef"

Password

Responses

200

200 OK

400

Bad Request

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/password-confirm

Production server (uses live data)

https://api.rayt.io//oauth/{version}/password-confirm

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/password-confirm

Request samples

application/json
Copy
Expand all Collapse all
{
  • "username": "user@rayt.io",
  • "verification_code": "123456789",
  • "password": "abcdefabcdef"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Password for user@rayt.io has been reset."
}

updatePassword

The password-change endpoint allows an authenticated user to change their password. The existing password must be provided, together with the new password.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Request details for password-change

access_token
string
Value:"1234abcd"

A valid authentication token. Note that this is the access_token as returned by the token endpoint, not the identity_token.

password_existing
string
Value:"abcdefabcdef"

The user's current password.

password_new
string
Value:"abcdefabcdefg"

The password to update to.

Responses

200

200 OK

400

Bad Request

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /oauth/{version}/password-change

Production server (uses live data)

https://api.rayt.io//oauth/{version}/password-change

Sandbox server (uses test data)

https://api-sandbox.rayt.io//oauth/{version}/password-change

Request samples

application/json
Copy
Expand all Collapse all
{
  • "access_token": "1234abcd",
  • "password_existing": "abcdefabcdef",
  • "password_new": "abcdefabcdefg"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Password for user@rayt.io has been changed."
}

org

Raytio Organisation APIs

List organisations

Retrieves the details of all organisations that the authenticated user can access.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

get /org/{version}

Production server (uses live data)

https://api.rayt.io//org/{version}

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "user": "dc734422-375a-4bea-abf8-a98ddd5456ab",
  • "organizations":
    [
    ],
  • "message": "Organizations assigned to the user dc734422-375a-4bea-abf8-a98ddd5456ab : yJUOp003tkWNqBl-hH-OOA,f0017d23_c8da_4501_9339_d84202c421f4."
}

Create an organisation

Creates a new organisation object.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

Request Body schema: application/json

Organisation request details

name
required
string

The name of the organisation

email
required
string

The billing email address of the organisation

address
Array of objects

The address of the organsation

customer
object

Billing information relating to this customer

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /org/{version}

Production server (uses live data)

https://api.rayt.io//org/{version}

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Test Organization 5",
  • "email": "hello@rayt.io",
  • "address":
    [
    ],
  • "customer":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Test Organization 5",
  • "email": "hello@rayt.io",
  • "address":
    [
    ],
  • "customer":
    {
    }
}

Retrieve an organisation

Retrieves the details of an existing organisation. You need only supply the unique organisation identifier that was returned upon organisation creation.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

orgID
required
string
Example: "de16ed4f-2dc1-4325-a41c-489cf6bad744"

The identifier of the organisation to be retrieved.

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

get /org/{version}/{orgID}

Production server (uses live data)

https://api.rayt.io//org/{version}/{orgID}

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/{orgID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Test Organization 5",
  • "email": "hello@rayt.io",
  • "address":
    [
    ],
  • "customer":
    {
    }
}

Update an organisation

Updates an existing organisation.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

orgID
required
string
Example: "de16ed4f-2dc1-4325-a41c-489cf6bad744"

The identifier of the organisation to be updated.

Request Body schema: application/json

Organisation request details

name
required
string

The name of the organisation

email
required
string

The billing email address of the organisation

address
Array of objects

The address of the organsation

customer
object

Billing information relating to this customer

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /org/{version}/{orgID}

Production server (uses live data)

https://api.rayt.io//org/{version}/{orgID}

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/{orgID}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Test Organization 5",
  • "email": "hello@rayt.io",
  • "address":
    [
    ],
  • "customer":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Test Organization 5",
  • "email": "hello@rayt.io",
  • "address":
    [
    ],
  • "customer":
    {
    }
}

Invite Organisation user

Invite an existing or new user to become a member of an organisation.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

orgID
required
string
Example: "de16ed4f-2dc1-4325-a41c-489cf6bad744"

The identifier of the organisation.

Request Body schema: application/json

Organisation invite request details

email
required
string

The email address of the user being invited to the organisation.

Responses

200

200 OK

400

Bad Request

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /org/{version}/{orgID}/invite

Production server (uses live data)

https://api.rayt.io//org/{version}/{orgID}/invite

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/{orgID}/invite

Request samples

application/json
Copy
Expand all Collapse all
{
  • "email": "user@rayt.io"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "The user user@rayt.io has been invited to join the Testing organization and an email with a verification code has been sent."
}

Verify organisation user

Validates the verification code and adds an invited user to the organisation.

path Parameters
version
required
string (api_version)
Value:"v1"

The API version

orgID
required
string
Example: "de16ed4f-2dc1-4325-a41c-489cf6bad744"

The identifier of the organisation.

Request Body schema: application/json

Organisation request details

verification_code_org
required
string

The verification code for the user being invited to the organisation.

Responses

200

200 OK

400

Bad Request

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

post /org/{version}/{orgID}/verify

Production server (uses live data)

https://api.rayt.io//org/{version}/{orgID}/verify

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/{orgID}/verify

Request samples

application/json
Copy
Expand all Collapse all
{
  • "verification_code_org": "abcd1234"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "User is verified."
}

List plans

List all available billing plans.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

query Parameters
active
boolean

Only return plans that are active or inactive (e.g., pass false to list all inactive products)

created
integer

A filter on the list based on the object created field. The value must be an integer Unix timestamp

ending_before
string

A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list

limit
integer

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10

product
string

Only return plans for the given product

starting_after
string

A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list

Responses

200

200 OK

400

Bad Request

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

get /org/{version}/plans

Production server (uses live data)

https://api.rayt.io//org/{version}/plans

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/plans

Response samples

application/json
Copy
Expand all Collapse all
{
  • "object": "list",
  • "data":
    [
    ],
  • "has_more": true,
  • "url": "v1/plans"
}

Retrieve a plan

Retrieves a specific billing plan.

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

planID
required
string
Example: "plan_EzSkxTLvWeHFKa"

The identifier of the plan to be retrieved.

Responses

200

200 OK

401

Unauthorized

500

Internal Server Error

502

Bad Gateway

get /org/{version}/plans/{planID}

Production server (uses live data)

https://api.rayt.io//org/{version}/plans/{planID}

Sandbox server (uses test data)

https://api-sandbox.rayt.io//org/{version}/plans/{planID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "plan_FC4dStqv9ZmDGK",
  • "object": "plan",
  • "active": true,
  • "aggregate_usage": "sum",
  • "amount": 100,
  • "billing_scheme": "per_unit",
  • "created": 1559669524,
  • "currency": "nzd",
  • "interval": "month",
  • "interval_count": 1,
  • "livemode": true,
  • "metadata": 1,
  • "nickname": "Credit bundle 550 NZ",
  • "product": "prod_EzQWJeGLEpVstW",
  • "tiers": null,
  • "tiers_mode": null,
  • "transform_usage": null,
  • "trial_period_days": null,
  • "usage_type": null
}

List subscriptions

By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled

Authorizations:
path Parameters
version
required
string (api_version)
Value:"v1"

The API version

orgID
required
string
Example: "de16ed4f-2dc1-4325-a41c-489cf6bad744"

The identifier of the organisation.

query Parameters
billing
boolean

The billing mode of the subscriptions to retrieve. Either charge_automatically or send_invoice

created
integer

A filter on the list based on the object created field. The value must be an integer Unix timestamp

current_period_end
integer

A filter on the list based on the object current_period_end field. The value must be an integer Unix timestamp

current_period_start
integer

A filter on the list based on the object current_period_start field. The value must be an integer Unix timestamp

customer
string

The ID of the customer whose subscriptions will be retrieved

ending_before
string

A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list

limit
integer

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10

plan
string

Only return plans for the given plan

starting_