> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Manage organizations with the API

> Learn how to create, read, update, and list boarding organizations with the Payabli API

> **Note**
>
> Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.

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](/guides/pay-ops-boarding-object-model-overview).

## Considerations

* The boarding API uses OAuth2. Send a Bearer token on every request. See [OAuth2 authentication](/developers/oauth-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](/guides/pay-ops-developer-businesses-manage#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](/guides/pay-ops-boarding-object-model-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](/developers/api-reference/organizations/create-an-organization) for this endpoint for full documentation.

This request creates the business inline:

### Request

POST [https://api-sandbox.payabli.com/api/v2/organizations](https://api-sandbox.payabli.com/api/v2/organizations)

**`CreateOrganizationInlineBusiness`**

```curl CreateOrganizationInlineBusiness
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"
}'
```

**`CreateOrganizationInlineBusiness`**

```typescript CreateOrganizationInlineBusiness
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.organizations.createOrganization({
        doingBusinessAs: "PropertyManager Pro",
        description: "Property management software partner",
        website: "https://example.com",
        customerServicePhone: "3055551212",
        customerServiceEmail: "support@example.com",
        timezone: "America/New_York",
        externalId: "pmp-org-001",
        business: {
            externalId: "pmp-biz-001",
            legalName: "PropertyManager Pro LLC",
            legalStructure: "llc",
        },
    });
}
main();

```

**`CreateOrganizationInlineBusiness`**

```python CreateOrganizationInlineBusiness
from payabli import payabli, CreateOrganizationWithInlineBusiness, CreateBusinessRequest

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.organizations.create_organization(
    request=CreateOrganizationWithInlineBusiness(
        doing_business_as="PropertyManager Pro",
        description="Property management software partner",
        website="https://example.com",
        customer_service_phone="3055551212",
        customer_service_email="support@example.com",
        timezone="America/New_York",
        external_id="pmp-org-001",
        business=CreateBusinessRequest(
            external_id="pmp-biz-001",
            legal_name="PropertyManager Pro LLC",
            legal_structure="llc",
        ),
    ),
)

```

**`CreateOrganizationInlineBusiness`**

```java CreateOrganizationInlineBusiness
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.organizations.types.CreateOrganizationOrganizationsRequest;
import io.github.payabli.api.types.CreateBusinessRequest;
import io.github.payabli.api.types.CreateBusinessRequestLegalStructure;
import io.github.payabli.api.types.CreateOrganizationWithInlineBusiness;
import java.util.Optional;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.organizations().createOrganization(
            CreateOrganizationOrganizationsRequest.of(
                CreateOrganizationWithInlineBusiness
                    .builder()
                    .doingBusinessAs("PropertyManager Pro")
                    .business(
                        CreateBusinessRequest
                            .builder()
                            .legalName("PropertyManager Pro LLC")
                            .externalId(Optional.of("pmp-biz-001"))
                            .legalStructure(Optional.of(CreateBusinessRequestLegalStructure.LLC))
                            .build()
                    )
                    .description(Optional.of("Property management software partner"))
                    .website(Optional.of("https://example.com"))
                    .customerServicePhone(Optional.of("3055551212"))
                    .customerServiceEmail(Optional.of("support@example.com"))
                    .timezone(Optional.of("America/New_York"))
                    .externalId(Optional.of("pmp-org-001"))
                    .build()
            )
        );
    }
}
```

**`CreateOrganizationInlineBusiness`**

```csharp CreateOrganizationInlineBusiness
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Organizations.CreateOrganizationAsync(
            new CreateOrganizationWithInlineBusiness {
                DoingBusinessAs = "PropertyManager Pro",
                Description = "Property management software partner",
                Website = "https://example.com",
                CustomerServicePhone = "3055551212",
                CustomerServiceEmail = "support@example.com",
                Timezone = "America/New_York",
                ExternalId = "pmp-org-001",
                Business = new CreateBusinessRequest {
                    ExternalId = "pmp-biz-001",
                    LegalName = "PropertyManager Pro LLC",
                    LegalStructure = CreateBusinessRequestLegalStructure.Llc
                }
            }
        );
    }

}

```

**`CreateOrganizationInlineBusiness`**

```go CreateOrganizationInlineBusiness
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.CreateOrganizationOrganizationsRequest{
        CreateOrganizationWithInlineBusiness: &payabli.CreateOrganizationWithInlineBusiness{
            Business: &payabli.CreateBusinessRequest{
                ExternalId: payabli.String(
                    "pmp-biz-001",
                ),
                LegalName: "PropertyManager Pro LLC",
                LegalStructure: payabli.CreateBusinessRequestLegalStructureLlc.Ptr(),
            },
            CustomerServiceEmail: payabli.String(
                "support@example.com",
            ),
            CustomerServicePhone: payabli.String(
                "3055551212",
            ),
            Description: payabli.String(
                "Property management software partner",
            ),
            DoingBusinessAs: "PropertyManager Pro",
            ExternalId: payabli.String(
                "pmp-org-001",
            ),
            Timezone: payabli.String(
                "America/New_York",
            ),
            Website: payabli.String(
                "https://example.com",
            ),
        },
    }
    client.Organizations.CreateOrganization(
        context.TODO(),
        request,
    )
}

```

**`CreateOrganizationInlineBusiness`**

```php CreateOrganizationInlineBusiness
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Types\CreateOrganizationWithInlineBusiness;
use Payabli\Types\CreateBusinessRequest;
use Payabli\Types\CreateBusinessRequestLegalStructure;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->organizations->createOrganization(
    new CreateOrganizationWithInlineBusiness([
        'doingBusinessAs' => 'PropertyManager Pro',
        'description' => 'Property management software partner',
        'website' => 'https://example.com',
        'customerServicePhone' => '3055551212',
        'customerServiceEmail' => 'support@example.com',
        'timezone' => 'America/New_York',
        'externalId' => 'pmp-org-001',
        'business' => new CreateBusinessRequest([
            'externalId' => 'pmp-biz-001',
            'legalName' => 'PropertyManager Pro LLC',
            'legalStructure' => CreateBusinessRequestLegalStructure::Llc->value,
        ]),
    ]),
);

```

**`CreateOrganizationInlineBusiness`**

```ruby CreateOrganizationInlineBusiness
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/organizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"business\": {\n    \"externalId\": \"pmp-biz-001\",\n    \"legalName\": \"PropertyManager Pro LLC\",\n    \"legalStructure\": \"llc\"\n  },\n  \"customerServiceEmail\": \"support@example.com\",\n  \"customerServicePhone\": \"3055551212\",\n  \"description\": \"Property management software partner\",\n  \"doingBusinessAs\": \"PropertyManager Pro\",\n  \"externalId\": \"pmp-org-001\",\n  \"timezone\": \"America/New_York\",\n  \"website\": \"https://example.com\"\n}"

response = http.request(request)
puts response.read_body
```

**`CreateOrganizationInlineBusiness`**

```swift CreateOrganizationInlineBusiness
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/organizations")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

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

### Request

POST [https://api-sandbox.payabli.com/api/v2/organizations](https://api-sandbox.payabli.com/api/v2/organizations)

**`CreateOrganization`**

```curl CreateOrganization
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"
}'
```

**`CreateOrganization`**

```typescript CreateOrganization
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.organizations.createOrganization({
        doingBusinessAs: "PropertyManager Pro",
        description: "Property management software partner",
        website: "https://example.com",
        timezone: "America/New_York",
        externalId: "pmp-org-001",
        businessReference: "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
    });
}
main();

```

**`CreateOrganization`**

```python CreateOrganization
from payabli import payabli, CreateOrganizationWithBusinessReference

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.organizations.create_organization(
    request=CreateOrganizationWithBusinessReference(
        doing_business_as="PropertyManager Pro",
        description="Property management software partner",
        website="https://example.com",
        timezone="America/New_York",
        external_id="pmp-org-001",
        business_reference="6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
    ),
)

```

**`CreateOrganization`**

```java CreateOrganization
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.organizations.types.CreateOrganizationOrganizationsRequest;
import io.github.payabli.api.types.CreateOrganizationWithBusinessReference;
import java.util.Optional;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.organizations().createOrganization(
            CreateOrganizationOrganizationsRequest.of(
                CreateOrganizationWithBusinessReference
                    .builder()
                    .doingBusinessAs("PropertyManager Pro")
                    .businessReference("6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27")
                    .description(Optional.of("Property management software partner"))
                    .website(Optional.of("https://example.com"))
                    .timezone(Optional.of("America/New_York"))
                    .externalId(Optional.of("pmp-org-001"))
                    .build()
            )
        );
    }
}
```

**`CreateOrganization`**

```csharp CreateOrganization
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Organizations.CreateOrganizationAsync(
            new CreateOrganizationWithBusinessReference {
                DoingBusinessAs = "PropertyManager Pro",
                Description = "Property management software partner",
                Website = "https://example.com",
                Timezone = "America/New_York",
                ExternalId = "pmp-org-001",
                BusinessReference = "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27"
            }
        );
    }

}

```

**`CreateOrganization`**

```go CreateOrganization
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.CreateOrganizationOrganizationsRequest{
        CreateOrganizationWithBusinessReference: &payabli.CreateOrganizationWithBusinessReference{
            BusinessReference: "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
            Description: payabli.String(
                "Property management software partner",
            ),
            DoingBusinessAs: "PropertyManager Pro",
            ExternalId: payabli.String(
                "pmp-org-001",
            ),
            Timezone: payabli.String(
                "America/New_York",
            ),
            Website: payabli.String(
                "https://example.com",
            ),
        },
    }
    client.Organizations.CreateOrganization(
        context.TODO(),
        request,
    )
}

```

**`CreateOrganization`**

```php CreateOrganization
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Types\CreateOrganizationWithInlineBusiness;
use Payabli\Types\CreateBusinessRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->organizations->createOrganization(
    new CreateOrganizationWithInlineBusiness([
        'doingBusinessAs' => 'PropertyManager Pro',
        'description' => 'Property management software partner',
        'website' => 'https://example.com',
        'timezone' => 'America/New_York',
        'externalId' => 'pmp-org-001',
        'business' => new CreateBusinessRequest([
            'legalName' => 'value',
        ]),
    ]),
);

```

**`CreateOrganization`**

```ruby CreateOrganization
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/organizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"businessReference\": \"6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27\",\n  \"description\": \"Property management software partner\",\n  \"doingBusinessAs\": \"PropertyManager Pro\",\n  \"externalId\": \"pmp-org-001\",\n  \"timezone\": \"America/New_York\",\n  \"website\": \"https://example.com\"\n}"

response = http.request(request)
puts response.read_body
```

**`CreateOrganization`**

```swift CreateOrganization
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/organizations")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

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

### Response (201)

```json
{
  "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](/developers/api-reference/organizations/get-an-organization) for this endpoint for full documentation.

### Request

GET [https://api-sandbox.payabli.com/api/v2/organizations/\{organizationReference}](https://api-sandbox.payabli.com/api/v2/organizations/\{organizationReference})

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

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.organizations.getOrganization("a8806f02-23b3-4f6d-bba3-42e1b94326ea");
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.organizations.get_organization(
    organization_reference="a8806f02-23b3-4f6d-bba3-42e1b94326ea",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.organizations().getOrganization("a8806f02-23b3-4f6d-bba3-42e1b94326ea");
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Organizations.GetOrganizationAsync(
            "a8806f02-23b3-4f6d-bba3-42e1b94326ea"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    client.Organizations.GetOrganization(
        context.TODO(),
        "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->organizations->getOrganization(
    'a8806f02-23b3-4f6d-bba3-42e1b94326ea',
);

```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The response returns the organization's full detail:

### Response (200)

```json
{
  "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](/developers/api-reference/organizations/list-organizations) for this endpoint for full documentation.

### Request

GET [https://api-sandbox.payabli.com/api/v2/organizations](https://api-sandbox.payabli.com/api/v2/organizations)

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

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.organizations.listOrganizations({
        businessReference: "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.organizations.list_organizations(
    business_reference="6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.organizations.requests.ListOrganizationsOrganizationsRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.organizations().listOrganizations(
            ListOrganizationsOrganizationsRequest
                .builder()
                .businessReference("6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27")
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Organizations.ListOrganizationsAsync(
            new ListOrganizationsOrganizationsRequest {
                BusinessReference = "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.ListOrganizationsOrganizationsRequest{
        BusinessReference: payabli.String(
            "6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27",
        ),
    }
    client.Organizations.ListOrganizations(
        context.TODO(),
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Organizations\Requests\ListOrganizationsOrganizationsRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->organizations->listOrganizations(
    new ListOrganizationsOrganizationsRequest([
        'businessReference' => '6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27',
    ]),
);

```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/organizations?businessReference=6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/organizations?businessReference=6e2b9d14-7a3c-4f58-b1e6-0c9d3a5f8e27")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The response returns a page of organizations with pagination metadata:

### Response (200)

```json
{
  "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](/developers/api-reference/organizations/update-an-organization) for this endpoint for full documentation.

### Request

PATCH [https://api-sandbox.payabli.com/api/v2/organizations/\{organizationReference}](https://api-sandbox.payabli.com/api/v2/organizations/\{organizationReference})

```curl
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"
}'
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        bearerAuth: {
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET",
        },
    });
    await client.organizations.updateOrganization("a8806f02-23b3-4f6d-bba3-42e1b94326ea", {
        description: "Updated description",
    });
}
main();

```

```python
from payabli import payabli

client = payabli(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

client.organizations.update_organization(
    organization_reference="a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    description="Updated description",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.organizations.requests.UpdateOrganizationRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient.withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
            .build()
        ;

        client.organizations().updateOrganization(
            "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
            UpdateOrganizationRequest
                .builder()
                .description("Updated description")
                .build()
        );
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new PayabliApiClient(
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        );

        await client.Organizations.UpdateOrganizationAsync(
            organizationReference: "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
            request: new UpdateOrganizationRequest {
                Description = "Updated description"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithClientCredentials(
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    request := &payabli.UpdateOrganizationRequest{
        Description: payabli.String(
            "Updated description",
        ),
    }
    client.Organizations.UpdateOrganization(
        context.TODO(),
        "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Organizations\Requests\UpdateOrganizationRequest;

$client = new PayabliClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
);
$client->organizations->updateOrganization(
    'a8806f02-23b3-4f6d-bba3-42e1b94326ea',
    new UpdateOrganizationRequest([
        'description' => 'Updated description',
    ]),
);

```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Updated description\"\n}"

response = http.request(request)
puts response.read_body
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["description": "Updated description"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/organizations/a8806f02-23b3-4f6d-bba3-42e1b94326ea")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The response confirms the update and returns the `updatedAt` timestamp:

### Response (200)

```json
{
  "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](/guides/pay-ops-developer-boarding-paypoints-manage)
* [Boarding overview](/guides/pay-ops-boarding-object-model-overview)
* [Organizations overview](/guides/pay-ops-organizations-overview)