Skip to main content
Sign in

Setup APIs

Jansi Hendry
  • Updated

Overview

The Setup APIs provide programmatic access to administrative and configuration settings within Ordway. These APIs allow you to retrieve and manage setup-related configurations, including notification settings, document numbering, company profile settings, user management, roles and permissions, SSO configuration, and user session settings.

The following Setup modules are currently supported:

User Session Settings

Get User Session Settings

Retrieves the configured inactivity timeout settings.

Endpoint

GET /api/v1/user_session_settings

Response

{

 "inactivity_time": 50,

 "inactivity_time_uom": "min"

}

Refer to Get User Session Settings | Ordway 

Update User Session Settings

Updates the inactivity timeout settings.

Endpoint

PUT /api/v1/user_session_settings

Request Body

{

 "inactivity_time": 50,

 "inactivity_time_uom": "min"

}

Response

{

 "message": "The inactivity time has been set."

}

Refer to Update User Session Settings | Ordway 

SSO Portal Configuration API

Get SSO Portal Configuration

Retrieves the current SSO portal configuration.

Endpoint

GET /api/v1/sso_portal/sso_config

Response

{

 "uuid": "9e35fbf4-176c-40a9-a0b7-3034b6801622",

 "provider": "oktas",

 "allow_logout_url": false,

 "logout_url": "https://login.ordwaylabs.com/logout",

 "allow_entity_id": false,

 "entity_id": "https://ordwaylabs.com/saml/metadata",

 "created_at": "2026-04-06T12:06:22.329Z",

 "updated_at": "2026-04-06T12:06:22.329Z",

 "target_url": "https://login.ordwaylabs.com/saml",

 "fingerprint": "AA:BB:CC:DD:EE:FF:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE",

 "created_by": "chaitanya.lokhande@ordwaylabs.com",

 "updated_by": "chaitanya.lokhande@ordwaylabs.com",

 "algorithm": "SHA256"

}

Refer to Get SSO Portal Configuration | Ordway 

Update SSO Portal Configuration

Updates the existing SSO portal configuration.

Endpoint

PUT /api/v1/sso_portal/update_config

Request Body

Exclude the following fields from the GET response:

  • uuid
  • created_at
  • updated_at
  • created_by
  • updated_by

Request Example

{

 "provider": "oktas",

 "allow_logout_url": false,

 "logout_url": "https://login.ordwaylabs.com/logout",

 "allow_entity_id": false,

 "entity_id": "https://ordwaylabs.com/saml/metadata",

 "target_url": "https://login.ordwaylabs.com/saml",

 "fingerprint": "AA:BB:CC:DD:EE:FF:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE",

 "algorithm": "SHA1"

}

Response

{

 "message": "Updated the SSO portal configuration successfully."

}

Error Response

Returned when invalid values are provided in the request.

Response

{

 "errors": {

   "algo": [

     "SHA12 is not valid. Allowed: SHA1, SHA256"

   ],

   "url": [

     "Target URL is not a valid URL"

   ],

   "fingerprint": [

     "Fingerprint is not valid"

   ]

 }

}

Refer to Update SSO Portal Configuration | Ordway 

Access-Based Response Behavior

Non-Admin User Response

For non-admin users, encrypted values are returned for protected SSO configuration fields.

Example Response

{

 "uuid": "e7be4a7c-3bdd-4341-9df4-409beb23449f",

 "provider": "$2a$10$YeNKrRsNvz/r33ccVYRUje6dgQU8dfyMPnhNTACC1sQ02zOuYTuWy",

 "allow_logout_url": false,

 "logout_url": "https://login.ordwaylabs.com/logout",

 "allow_entity_id": false,

 "entity_id": "https://ordwaylabs.com/saml/metadata",

 "created_at": "2025-11-18T10:23:29.010Z",

 "updated_at": "2026-04-06T11:13:02.156Z",

 "target_url": "f7e135d25def1983507011b937c9fe7d5b2d768f9fa48d33445d76530fddfa2545ec015465cb23b99dba40bfe521a261",

 "fingerprint": "42b60bd3e4a683b7ec64b448b05dc7ad",

 "created_by": "chaitanya.lokhande@ordwaylabs.com",

 "updated_by": "chaitanya.lokhande@ordwaylabs.com"

}

Admin User Response

For admin users, decrypted SSO configuration values are returned.

Example Response

{

 "uuid": "9e35fbf4-176c-40a9-a0b7-3034b6801622",

 "provider": "oktas",

 "allow_logout_url": false,

 "logout_url": "https://login.ordwaylabs.com/logout",

 "allow_entity_id": false,

 "entity_id": "https://ordwaylabs.com/saml/metadata",

 "created_at": "2026-04-06T12:06:22.329Z",

 "updated_at": "2026-04-06T12:06:22.329Z",

 "target_url": "https://login.ordwaylabs.com/saml",

 "fingerprint": "AA:BB:CC:DD:EE:FF:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE",

 "created_by": "chaitanya.lokhande@ordwaylabs.com",

 "updated_by": "chaitanya.lokhande@ordwaylabs.com"

}

Audit Events

Audit events capture updates made to the SSO portal configuration.

  • Admin users can view decrypted configuration values.
  • Non-admin users receive encrypted values for protected fields.

Refer to Get SSO Portal Configuration | Ordway 

Notification Settings API

Get Notification Settings

Retrieves the configured notification settings.

Endpoint

GET /api/v1/notifications

Response

{

 "notification_settings": [

   {

     "event_type": "Import Data",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Quotes",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Billing Run",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Payment Run",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Subscriptions",

     "email_enabled": false,

     "notification_enabled": false

   }

 ]

}

Response Fields

Field Type Description
event_type String Notification event type.
email_enabled Boolean Indicates whether email notifications are enabled.
notification_enabled Boolean Indicates whether in-app notifications are enabled.

Refer to Get Notification Settings | Ordway

Update Notification Settings

Updates the notification settings configuration.

Endpoint

PUT /api/v1/notifications

Request Body

{

 "notification_settings": [

   {

     "event_type": "Import Data",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Quotes",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Billing Run",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Payment Run",

     "email_enabled": false,

     "notification_enabled": true

   },

   {

     "event_type": "Subscriptions",

     "email_enabled": false,

     "notification_enabled": false

   }

 ]

}

Response

{

 "message": "Notification settings updated successfully"

}

 

Error Response

Returned when the required request parameter is missing.

Response

{

 "errors": {

   "details": {

     "message": "notification_settings param is required"

   }

 }

}

Refer to Update Notification Settings | Ordway

Document Numbering API

The Document Numbering module controls how unique numbers are generated for supported document types.

Numbering Rules

Documents support the following numbering rules:

  • auto — System-generated numbering
  • manual — User-provided numbering

Manual Rule Behavior

For documents configured with the manual rule:

  • next_number is not modified.
  • The system does not increment or use next_number.

System-Generated Documents

The following document types support only automatic numbering and cannot be configured with the manual rule:

  • BillingRun ID
  • BillingSchedule ID
  • Dispute ID
  • Invoice ID
  • JournalEntry ID
  • JournalEntryRun ID
  • ModuleImport ID
  • OtherTransaction ID
  • Payment ID
  • PaymentRun ID
  • Payout ID
  • Refund ID
  • RevenueSchedule ID
  • Tax ID

Get Document Numberings

Retrieves document numbering configurations.

Endpoint

GET /api/v1/document_numbering

Query Parameters

Parameter Description
documents Filters response by document types. Multiple values can be passed as comma-separated values.

Example

GET /api/v1/document_numbering?documents=ApprovalProcess,BillingRun

Response

{

 "document_numberings": [

   {

     "document": "Tax ID",

     "rule": "auto",

     "prefix": "TX-",

     "next_number": 18,

     "controlled_by": "Parent Entity"

   },

   {

     "document": "Payment ID",

     "rule": "auto",

     "prefix": "PAY-",

     "next_number": 102,

     "controlled_by": "Parent Entity"

   }

 ]

}

Behavior

  • Returns all document numbering records when no query parameter is provided.
  • Returns only matching document types when the document's query parameter is used.

Refer to Get Document Numbering | Ordway

Update Document Numberings

Updates document numbering configurations.

Endpoint

PUT /api/v1/document_numbering

Request Body

{
"document_numberings": [
{
"document": "Tax ID",
"rule": "auto",
"prefix": "TX-",
"next_number": 18,
"controlled_by": "Parent Entity"
},
{
"document": "Payment ID",
"rule": "auto",
"prefix": "PAY-",
"next_number": 102,
"controlled_by": "Parent Entity"
}
]
}
 

Note: Include controlled_by": "Parent Entity only when updating document numbering for a child entity after document numbering has been shared from the parent entity using the Enable Numbering for Entities setting.

Validation Rules

Field Validation
rule Allowed values: auto, manual
rule Manual rule is not allowed for system-generated document types
next_number Required when rule = auto
next_number Must be greater than 0
prefix Supports - and _. Other special characters are not allowed

Update Logic

For each document numbering record:

  1. Find the document numbering record scoped to the company.
  2. Validate the requested rule update.
  3. Apply updates based on the selected rule.
  4. Save the updated record.

Rule Behavior

Auto Rule

When rule = auto, the following fields are updated:

  • prefix
  • next_number

Validation:

  • next_number must be greater than 0.

Manual Rule

When rule = manual:

  • next_number is not modified.

Partial Updates

Partial updates are supported.

If validation fails for a record, the corresponding error is returned for that document.

Success Response

{

 "message": "Document numberings updated successfully"

}

Error Responses

Manual Numbering Not Allowed

{

 "errors": [

   {

     "document": "BillingSchedule ID",

     "message": "Manual numbering is not allowed for this document"

   }

 ]

}

Missing Next Number

{

 "errors": [

   {

     "document": "Charge ID",

     "message": "next_number is required for auto rule"

   }

 ]

}

Company Profile API

Get Company Profile

Retrieves the company profile configured in the request headers.

Endpoint

GET /api/v1/companies/company_profile

Response

{

 "id": "18e0b47f-2001-4d40-8b6c-2c01415d919e",

 "name": "Settings Company 101",

 "email": "",

 "phone": "",

 "address": {

   "address1": "",

   "address2": "",

   "city": "",

   "state": "",

   "zip": "",

   "country": "United States of America"

 },

 "company_type": "",

 "terms_and_conditions_url": "",

 "privacy_policy_url": "",

 "display_terms_and_privacy": false,

 "hosted_pages_sub_url": "SettingsCompany101",

 "logo_url": "",

 "created_at": "2026-03-03T03:52:18.398Z",

 "updated_at": "2026-04-10T07:23:35.686Z"

}

Refer to Get Company Profile | Ordway

Create Company

Creates a company.

Endpoint

POST /api/v1/companies

Request Body

{

 "name": "New api company 2"

}

Response

{

 "id": "b4c647f8-cb2c-497b-89c6-076f418153f7",

 "name": "New api company 2",

 "email": "",

 "phone": "",

 "address": {

   "address1": "",

   "address2": "",

   "city": "",

   "state": "",

   "zip": "",

   "country": "United States of America"

 },

 "company_type": "",

 "terms_and_conditions_url": "",

 "privacy_policy_url": "",

 "display_terms_and_privacy": false,

 "hosted_pages_sub_url": "Newapicompany2",

 "logo_url": "",

 "created_at": "2026-04-10T06:59:02.253Z",

 "updated_at": "2026-04-10T06:59:06.538Z"

}

 

Refer to Create Company | Ordway

Update Company

Updates company profile details.

Endpoint

PUT /api/v1/companies/:uuid

Request Body

{

 "name": "New api company 2",

 "email": "chaitanya.lokhande+02@ordwaylabs.com",

 "phone": "",

 "address": {

   "address1": "",

   "address2": "",

   "city": "",

   "state": "",

   "zip": "",

   "country": "United States of America"

 },

 "company_type": 1,

 "terms_and_conditions_url": "",

 "privacy_policy_url": "",

 "display_terms_and_privacy": true,

 "hosted_pages_sub_url": "Newapicompany2",

 "logo_url": ""

}

Refer to Update Company | Ordway

Change Company Type

Updates the company type.

Endpoint

PUT /api/v1/companies/:uuid/change_company_type

Request Body

{

 "company_type": "Tests"

}

Error Response

{

 "errors": {

   "details": {

     "message": "Invalid company_type. Allowed values: Trial, Test, Active, Expired, Terminated"

   }

 }

}

Refer to Change Company Type | Ordway

Users API

Get Users

Retrieves users.

Endpoint

GET /api/v1/users

Hidden Fields

The following fields are not returned in the response:

  • authentication_token
  • confirmation_token
  • otp_secret
  • encrypted_password
  • reset_password_token
  • user_id
  • filters
  • sortings
  • unlock_token
  • otp_backup_codes
  • unique_session_id
  • proxy_grand_ticket

Refer to List Users | Ordway

Get User

Retrieves a specific user.

Endpoint

GET /api/v1/users/:uuid

Update User

Updates user details and entity role assignments.

Endpoint

PUT /api/v1/users/:id

Response

{

 "message": "User successfully updated"

}

Refer to Get User | Ordway

Create User

Creates a user.

Endpoint

POST /api/v1/users

Response

{
"message": "User successfully added",
"data": {
"user": {
"id": "",
"email": "XXX.YYY167@ordwaylabs.com",
"name": "XXX167",
"active": "",
"sso_setup": "",
"mfa_setup": "",
"role": "",
"user_preferences": {
"date_format": "YYYY/MM/DD",
"rows_per_page": 25,
"rows_per_line_items": 5,
"plans_per_page": 5,
"charges_per_plan": 5
}
},
"entities": {}
}
}

Refer to Create User | Ordway

Change Token

Regenerates the user token.

Endpoint

POST /api/v1/users/:id/change_token

Response

{

 "message": "Token successfully regenerated for chaitanyalokhande."

}

Refer to Change Token | Ordway

Unlock Account

Unlocks a locked user account.

Endpoint

PUT /api/v1/users/:id/unlock_account

Response

{

 "message": "User chaitanyalokhande successfully unlocked"

}

Refer to Unlock Account | Ordway

Additional User Actions

Action Endpoint
Resend Confirmation Email POST /api/v1/users/:id/resend_confirmation_email
Download Recovery Codes GET /api/v1/users/:id/download_recovery_codes
Delete MFA Setup POST /api/v1/users/:id/delete_mfa_setup
Delete User DELETE /api/v1/users/:id

Roles and Permissions API

Get Roles

Retrieves all roles.

Endpoint

GET /api/v1/roles

Refer to Get Roles | Ordway

Get Role with Permissions

Retrieves a role and its associated permissions.

Endpoint

GET /api/v1/roles/:role_uuid

Refer to Get Role with Permissions | Ordway

Create Role

Creates a role with permissions.

Endpoint

POST /api/v1/roles

Response

{

 "message": "Role successfully created"

}

Refer to Create Role | Ordway

Update Role

Update's role details and permissions.

Endpoint

PUT /api/v1/roles/:id

Notes

  • Partial permission updates are supported.
  • Validation is performed on module, activity, and permissions.

Response

{

 "message": "Role successfully updated"

}

Refer to Update Role | Ordway

Delete Role

Deletes a role.

Endpoint

DELETE /api/v1/roles/:role_uuid

Success Response

{

 "message": "Role successfully deleted."

}

Error Response

{

 "errors": {

   "details": {

     "message": {

       "role": [

         "Product Creator is in use and can't be deleted"

       ]

     }

   }

 }

}

Refer to Delete Role | Ordway

Was this article helpful?
0 out of 0 found this helpful
Please sign in to submit a request.
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.