Manage organizations with the API

An organization groups the paypoints, suborganizations, and templates under it. Use the organizations API to create and manage organizations as part of boarding. For how organizations fit into the wider model, see the boarding overview.

Considerations

• The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
• An organization belongs to a business. Create the business inline with the organization, or use an existing business. Inline is the recommended approach.
• An organization isn’t underwritten, so creating one doesn’t require the business details that a merchant application does. Set description, website, customerServicePhone, customerServiceEmail, and timezone when you have them. On the organization’s business, include basic details such as its legal address, email addresses, and phone number.
• To give an organization main points of contact, add the business’s owners or employees as people. Provide whatever details are useful to you. Underwriting details aren’t required. See Manage the people on a business.
• An organization’s settings, such as billing, risk, and funding, pass down to the suborganizations you create under it. Payabli turns these settings on, and you can’t change them with the API. See Boarding overview.
• In intelligent boarding, an organization is a kind of paypoint. It uses the same fields and response shapes as a paypoint, and its paypointType is organization. The organizations endpoints return only organizations, never other paypoints.
• There’s no endpoint to delete an organization.

Create an organization

Send a POST request to /v2/organizations with the organization’s doingBusinessAs and its business. Provide either a business object to create the business inline, or a businessReference for an existing business. The request takes the same fields as creating a paypoint, except paypointType, because Payabli sets the organization type for you. If you don’t set parentPaypointReference, the new organization nests under the organization your credential belongs to. See the API reference for this endpoint for full documentation.

This request creates the business inline:

curl -X POST https://api-sandbox.payabli.com/api/v2/organizations \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "business": {
    "externalId": "pmp-biz-001",
    "legalName": "PropertyManager Pro LLC",
    "legalStructure": "llc"
  },
  "customerServiceEmail": "support@example.com",
  "customerServicePhone": "3055551212",
  "description": "Property management software partner",
  "doingBusinessAs": "PropertyManager Pro",
  "externalId": "pmp-org-001",
  "timezone": "America/New_York",
  "website": "https://example.com"
}'

To use an existing business instead, send a businessReference rather than a business object:

curl -X POST https://api-sandbox.payabli.com/api/v2/organizations \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "businessReference": "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
  "description": "Property management software partner",
  "doingBusinessAs": "PropertyManager Pro",
  "externalId": "pmp-org-001",
  "timezone": "America/New_York",
  "website": "https://example.com"
}'

The response returns the new organization’s reference, its business reference, and its initial status. New organizations start in pending:

{
  "success": true,
  "message": "Organization created successfully",
  "traceId": "0HNPE4LGV8483:000006C9",
  "data": {
    "paypointReference": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "paypointStatus": "pending",
    "createdAt": "2026-10-20T22:20:37.0295891Z",
    "_links": {
      "self": "/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea",
      "business": "/v2/businesses/6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27"
    },
    "businessReference": "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
    "doingBusinessAs": "PropertyManager Pro",
    "timezone": "America/New_York"
  }
}

Use the paypointReference in the response to read and manage the organization. The externalId is optional. If an organization with the same externalId already exists, the request fails with 409.

Get an organization

Send a GET request to /v2/organizations/{organizationReference}. See the API reference for this endpoint for full documentation.

curl https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea \
     -H "Authorization: Bearer <token>"

The response returns the organization’s full detail:

{
  "success": true,
  "message": "Organization retrieved successfully",
  "traceId": "0HNPE4LGV825M:0000001D",
  "data": {
    "paypointReference": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "parentPaypointReference": "3c7f1a9e-5d2b-4e84-a6c0-8b1f4d7e2a95",
    "paypointStatus": "pending",
    "entryName": "8cfec329267",
    "createdAt": "2026-10-20T22:20:37.029589",
    "updatedAt": "2026-10-20T22:20:37.029589",
    "_links": {
      "self": "/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea",
      "business": "/v2/businesses/6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27"
    },
    "businessReference": "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
    "paypointType": "organization",
    "doingBusinessAs": "PropertyManager Pro",
    "description": "Property management software partner",
    "website": "https://example.com",
    "timezone": "America/New_York",
    "externalId": "pmp-org-001"
  }
}

List organizations

Send a GET request to /v2/organizations. Filter and page the results with the query parameters: businessReference, status, search, limit, and page. The status filter accepts active, inactive, suspended, or closed, and any other value returns 400. See the API reference for this endpoint for full documentation.

curl -G https://api-sandbox.payabli.com/api/v2/organizations \
     -H "Authorization: Bearer <token>" \
     -d businessReference=6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27

The response returns a page of organizations with pagination metadata:

{
  "success": true,
  "message": "Organizations retrieved successfully",
  "traceId": "0HNPE4LGV825H:00000033",
  "data": {
    "items": [
      {
        "paypointReference": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
        "parentPaypointReference": "3c7f1a9e-5d2b-4e84-a6c0-8b1f4d7e2a95",
        "paypointStatus": "pending",
        "entryName": "8cfec329267",
        "createdAt": "2026-10-20T22:20:37.029589",
        "updatedAt": "2026-10-20T22:20:37.029589",
        "_links": {
          "self": "/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea",
          "business": "/v2/businesses/6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27"
        },
        "businessReference": "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
        "paypointType": "organization",
        "doingBusinessAs": "PropertyManager Pro",
        "description": "Property management software partner",
        "website": "https://example.com",
        "timezone": "America/New_York",
        "externalId": "pmp-org-001"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 25
  }
}

Update an organization

Send a PATCH request to /v2/organizations/{organizationReference} with only the fields you want to change. You can’t change an organization’s type. If you send paypointType, the request ignores it and doesn’t return an error. See the API reference for this endpoint for full documentation.

curl -X PATCH https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "description": "Updated description"
}'

The response confirms the update and returns the updatedAt timestamp:

{
  "success": true,
  "message": "Organization updated successfully",
  "traceId": "0HNPE4LB0RHAE:0000003F",
  "data": {
    "paypointReference": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "updatedAt": "2026-10-20T22:20:37.3467166Z",
    "_links": {
      "self": "/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea"
    }
  }
}

Related resources

• Manage paypoints with the API
• Boarding overview
• Organizations overview