# Handling

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## GET /handling/{datatype}/{id}

**Who is dealing with a record**

`operationId: HandlingController_get`

The record's handling: status (open, in_progress, done, no_action), who has it, since when, the outcome, and its history. Null when nothing tracks it.

#### Signature

```http
GET /handling/{datatype}/{id} (datatype: string, id: string) -> The handling, or null
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `datatype` | path | string | yes | The record's collection, e.g. ticket, message, social_activity, sf_order. |
| `id` | path | string | yes | The record id (sk). |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The handling, or null |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /handling/{datatype}/{id}/take

**Take a record**

`operationId: HandlingController_take`

Take it before working on it. Succeeds only while nobody has it — two taking at once, one wins. Returns { taken: true } or { taken: false, message } naming who has it; then leave it.

#### Signature

```http
POST /handling/{datatype}/{id}/take (datatype: string, id: string) -> { taken, handling, message? }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /handling/{datatype}/{id}/done`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `datatype` | path | string | yes | The record's collection, e.g. ticket, message, social_activity, sf_order. |
| `id` | path | string | yes | The record id (sk). |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { taken, handling, message? } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /handling/{datatype}/{id}/done

**Finish a record**

`operationId: HandlingController_done`

It is dealt with. `outcome` is one line on what was done.

#### Signature

```http
POST /handling/{datatype}/{id}/done (datatype: string, id: string, body) -> { handling }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `datatype` | path | string | yes | The record's collection, e.g. ticket, message, social_activity, sf_order. |
| `id` | path | string | yes | The record id (sk). |

### Request body

What was done.

```json
{
  "outcome": "Replied with opening hours."
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { handling } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /handling/{datatype}/{id}/no-action

**Close a record — nothing needed**

`operationId: HandlingController_noAction`

Nothing needs doing (spam, already answered…). `reason` says why.

#### Signature

```http
POST /handling/{datatype}/{id}/no-action (datatype: string, id: string, body) -> { handling }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `datatype` | path | string | yes | The record's collection, e.g. ticket, message, social_activity, sf_order. |
| `id` | path | string | yes | The record id (sk). |

### Request body

Why nothing is needed.

```json
{
  "reason": "Duplicate of another ticket."
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { handling } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /handling/{datatype}/{id}/release

**Give a record back**

`operationId: HandlingController_release`

Open it again for anyone to take — when you cannot finish it, or to reopen a finished one.

#### Signature

```http
POST /handling/{datatype}/{id}/release (datatype: string, id: string, body) -> { released, handling }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `datatype` | path | string | yes | The record's collection, e.g. ticket, message, social_activity, sf_order. |
| `id` | path | string | yes | The record id (sk). |

### Request body

Optional reason.

```json
{
  "reason": "Needs someone with billing access."
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { released, handling } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |