---
name: hedge-dedesignations
description: >
  Instructs AI agents how to de-designate a transaction from a hedge
  relationship in Kyriba. Used in FX hedging lifecycle management.
  Single-action API - one endpoint only.
version: 1.0.0
scopes:
  - hr-dedesignation-scope
authors:
  - kyriba
tags:
  - kyriba
  - risk
  - hedge
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Hedge De-Designations

---

## Required Kyriba Permission

```
hr-dedesignation-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

>  This scope is **not enabled by default**. Contact Kyriba support to enable it for your API client.

---

## What is De-designation?

De-designation removes a financial transaction from a hedge relationship as of a specific date. Used when:
- A hedging relationship no longer qualifies for hedge accounting
- The hedge design changes
- Hedging instruments or items change frequently

---

## Base Path

```
/v1/hedge-accounting/dedesignation
```

---

## Endpoints

This API has **one endpoint only:**

| Method | Path | Description |
|--------|------|-------------|
| `PUT` | `/v1/hedge-accounting/dedesignation/hedge-relationship/{relationship-number}/transaction/{transaction-number}/dedesignate` | De-designate a transaction from a hedge relationship |

---

## Path Parameters

| Parameter | Format | Example | Description |
|---|---|---|---|
| `relationship-number` | `HR######` | `HR123456` | Hedge relationship ID generated by Kyriba |
| `transaction-number` | Numeric string | `123456789` | Financial transaction ID |

---

## Request Body

```http
PUT /v1/hedge-accounting/dedesignation/hedge-relationship/HR123456/transaction/123456789/dedesignate
Content-Type: application/json

{
  "date": "2025-07-08",
  "deDesignatedValue": "FROM_PREVIOUS_ASSESSMENT_DATE"
}
```

| Field | Required | Values | Description |
|---|---|---|---|
| `date` |  Yes | `YYYY-MM-DD` | Date of de-designation |
| `deDesignatedValue` | No | `AS_OF_DEDESIGNATION_DATE` \| `FROM_PREVIOUS_ASSESSMENT_DATE` | Settlement value source. Default: `FROM_PREVIOUS_ASSESSMENT_DATE` |

---

## Response (`200 OK`)

```json
{ "status": "TRANSACTION_DEDESIGNATED" }
```

| Status value | Meaning |
|---|---|
| `TRANSACTION_DEDESIGNATED` | Only this transaction was de-designated |
| `HEDGE_RELATIONSHIP_DEDESIGNATED` | The entire hedge relationship was de-designated |

---

## Error Codes (`400`)

| Functional code | Message | When |
|---|---|---|
| `Invalid` | Invalid input | Date format incorrect |
| `1` | Invalid hedge relationship | Relationship cannot be retrieved |
| `2` | Transaction does not exist in the hedge relationship | Transaction ID not linked to this relationship |
| `3` | Transaction cannot be de-designated | Item is already de-designated or ineligible |
| `10` | De-designation not applicable | Relationship is Cancelled, Pending, or De-designated |
| `11` | Error saving hedge relationship | Validation failure (dates, allocation, etc.) |
| `12` | Partial de-designation detected | Transaction was previously partially de-designated via UI |
| `13` | No transaction exists on reclass start date | De-designation date before reclass schedule begins |

---

## Critical Rules

1. `hr-dedesignation-scope` must be **explicitly enabled** by Kyriba support
2. `date` is required - format is `YYYY-MM-DD`
3. Only **hedged** and **hedging items** can be de-designated
4. Partial de-designations via the UI block subsequent API de-designation (error code `12`)
5. `relationship-number` format is `HR######` - six digits with `HR` prefix

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Successful |
| `400` | Functional error - see error codes table |
| `401` | Expired or missing token |
| `403` | Required Kyriba permission not configured on your API client |
| `415` | Wrong Content-Type (must be `application/json`) |
| `500` | Unexpected server error |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/hedge-dedesignations/hedge-dedesignations.yaml`
- Postman: `https://developer.kyriba.com/static/apis/hedge-dedesignations/hedge-dedesignations-postman-collection.json`