# Use Cases for Organization

| I want to <div style="width:230px"></div>                                                                                      | Request Type                                                  | Example URL <div style="width:190px"></div>                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve and display details of a particular organization.                                                                     | [GET by ID](#get-by-id)                                       | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}*<br><br>**NOTE:**<br>For an invalid ID, you receive HTTP 404 error.                                              |
| Based on the provided field values, retrieve and display details of organizations.                                             | [GET with Fields](#get-with-fields)                           | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?fields=name,organizationType*<br><br>**NOTE:**<br>The requested fields are part of the output if they have a value.   |
| List all the organizations present in the system.                                                                              | [GET List](#get-list)                                         | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization*                                                                                                                      |
| List organizations present in the system based on the filter applied.                                                          | [GET List with Filtering](#get-list-with-filtering)           | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?name=Acme*<br><br>**NOTE:**<br>The requested fields are part of the output if they have a value.                      |
| List organizations, limit the number of records to a specified limit, and start the results from the page specified by offset. | [GET List by limit and offset](#get-list-by-limit-and-offset) | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?offset=4&pageLimit=1&pageinfo=true*                                                                                   |
| Create a new organization by providing the required details.                                                                   | [POST](#post)                                                 | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization*<br><br>**NOTE:**<br>A new organization is created based on the values mentioned for the mandatory fields.            |
| Update details of a particular organization.                                                                                   | [PATCH](#patch)                                               | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}*                                                                                                                 |
| Delete an organization.                                                                                                        | [DELETE](#delete)                                             | *{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}*<br><br>**NOTE:**<br>DELETE requires an Apex extensibility implementation. Without it, the API returns HTTP 400. |

## GET by ID

Consider you want to retrieve details of a particular organization.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}`

### Sample Response

```
{
    "id": "001xx000003GkRbAAK",
    "href": "/connect/comms/partymanagement/v5/organization/001xx000003GkRbAAK",
    "name": "Acme Corporation",
    "organizationType": "Partner",
    "contactMedium": [
        {
            "phoneNumber": "+1-555-0300",
            "@type": "PhoneContactMedium"
        },
        {
            "faxNumber": "+1-555-0301",
            "@type": "FaxContactMedium"
        },
        {
            "city": "San Francisco",
            "country": "US",
            "postCode": "94105",
            "stateOrProvince": "CA",
            "street1": "1 Market Street",
            "@type": "GeographicAddressContactMedium"
        }
    ],
    "@type": "Organization"
}
```

## GET with Fields

Consider you want to retrieve organizations and return only these fields in the output.

- name
- organizationType

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?fields=name,organizationType`

### Sample Response

```
[
    {
        "id": "001xx000003GkRbAAK",
        "href": "/connect/comms/partymanagement/v5/organization/001xx000003GkRbAAK",
        "name": "Acme Corporation",
        "organizationType": "Partner",
        "@type": "Organization"
    }
]
```

## GET List

Consider there are multiple organizations in the system and you want to list all of them.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization`

## GET List with Filtering

Consider you want to retrieve organizations with applied filter values.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?name=Acme`

### Sample Response

```
[
    {
        "id": "001xx000003GkRbAAK",
        "href": "/connect/comms/partymanagement/v5/organization/001xx000003GkRbAAK",
        "name": "Acme Corporation",
        "organizationType": "Partner",
        "@type": "Organization"
    }
]
```

## GET List by limit and offset

Consider you want to retrieve a list of organizations, limit the number of records, and start the results from the specified offset.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization?offset=4&pageLimit=1&pageinfo=true`

## POST

Consider you want to create a new organization. `name` is mandatory.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization`

### Sample Request

```
{
    "@type": "Organization",
    "name": "Minimal Org"
}
```

### Sample Response

```
{
    "id": "001xx000003H8NWAA0",
    "href": "/connect/comms/partymanagement/v5/organization/001xx000003H8NWAA0",
    "name": "Minimal Org",
    "@type": "Organization"
}
```

## PATCH

Consider you want to update details of a particular organization.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}`

### Sample Request

```
{
    "@type": "Organization",
    "name": "Acme Corp Updated",
    "contactMedium": [
        {
            "@type": "PhoneContactMedium",
            "phoneNumber": "+1-555-0400"
        },
        {
            "@type": "GeographicAddressContactMedium",
            "street1": "789 Pine Road",
            "city": "Austin",
            "stateOrProvince": "TX",
            "postCode": "73301",
            "country": "US"
        }
    ],
    "organizationParentRelationship": {
        "organization": {
            "id": "001xx000003GkTDAA0"
        }
    }
}
```

## DELETE

Account does not include a status field that supports soft delete out of the box. The DELETE endpoint is provided as an extensibility hook. Without a custom Apex implementation, the API returns HTTP 400.

### Sample URL

`{{orgendpoint}}/services/data/{{version}}/connect/comms/partymanagement/v5/organization/{ID}`

### Sample Request

No request body.

### Sample Response

With an Apex extensibility implementation: HTTP 204 with no response body.

Without extensibility:

```
[
    {
        "errorCode": "BAD_REQUEST",
        "message": "DELETE operation for organisation requires an extensibility class implementing comms_apex_ext.IOrganizationPartyManagementDELETE. Configure a custom Apex class that provides a soft-delete status field via the customiseMutationPayload hook."
    }
]
```