> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fynapse.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fynapse.app/_mcp/server.

# Create or replace the Business Event Definition

PUT https://api.fynapse.com/api/v1/configuration/business-event-definition
Content-Type: application/json

This endpoint is an idempotent upsert of your single Business Event Definition. It is a full replace: attributes and validations omitted from the body are removed.

To create the Business Event Definition, send no `If-Match`, or send `If-None-Match: *` to make the request fail if a Business Event Definition already exists. To replace it, `If-Match` is required and must carry the `ETag` from your last read - omitting it is rejected with 428, and a stale value with 412.

Validations can be created only for attributes defined in the Business Event Definition. A change is refused with 409 if accounting rules still use on an attribute that the change removes in their configuration, or if the attribute's type or role it changes.

The change takes effect immediately and does not go through an approval workflow, so the response is always 201 or 200. Your user also needs permission to view and edit data structures.

If part of the setup could not be completed straight away, the response lists it in `warnings`. The Business Event Definition is saved and the setup finishes by itself, so you do not need to resend the request.

Reference: https://docs.fynapse.app/api-reference/api-reference/data-model/business-event-definition/put-business-event-definition

## Authentication

- OAuth2 — send the obtained token as `Authorization: Bearer <token>`

## Request

### Headers

- `If-Match` (string, optional) — The `ETag` from your last read of the resource. Required when replacing an existing resource, and omitted when creating one.
- `If-None-Match` (enum, optional) — Send `*` for create-only semantics - the request then fails if the resource already exists.
  - Allowed values: `*`

### Body (application/json)

This endpoint expects a schema.BusinessEventDefinition.

- `effectiveFrom` (string, optional) — Date from which the definition applies. When omitted, today's date is used on create and the stored date is kept on replace.
- `attributes` (list of schema.BusinessEventAttribute, optional) — Every attribute of a business event, in order. A write replaces the whole list.
- `primaryKeys` (list of string, optional) — Names of the attributes that together identify an event. Each must be one of the attributes.
- `validations` (list of schema.EntityValidation, optional) — Rules every incoming event must satisfy. Every attribute a rule refers to must be one of the attributes above. A write replaces the whole list, so omitting it or sending an empty list removes every validation.
- `warnings` (list of schema.ProvisioningWarning, optional) — Parts of the setup that could not be completed straight away when you saved. The definition is saved and the setup finishes by itself. Absent when there is nothing to report.

## Response

### 200

OK

- `effectiveFrom` (string, optional) — Date from which the definition applies. When omitted, today's date is used on create and the stored date is kept on replace.
- `attributes` (list of schema.BusinessEventAttribute, optional) — Every attribute of a business event, in order. A write replaces the whole list.
- `primaryKeys` (list of string, optional) — Names of the attributes that together identify an event. Each must be one of the attributes.
- `validations` (list of schema.EntityValidation, optional) — Rules every incoming event must satisfy. Every attribute a rule refers to must be one of the attributes above. A write replaces the whole list, so omitting it or sending an empty list removes every validation.
- `warnings` (list of schema.ProvisioningWarning, optional) — Parts of the setup that could not be completed straight away when you saved. The definition is saved and the setup finishes by itself. Absent when there is nothing to report.

### 201

Created

- `effectiveFrom` (string, optional) — Date from which the definition applies. When omitted, today's date is used on create and the stored date is kept on replace.
- `attributes` (list of schema.BusinessEventAttribute, optional) — Every attribute of a business event, in order. A write replaces the whole list.
- `primaryKeys` (list of string, optional) — Names of the attributes that together identify an event. Each must be one of the attributes.
- `validations` (list of schema.EntityValidation, optional) — Rules every incoming event must satisfy. Every attribute a rule refers to must be one of the attributes above. A write replaces the whole list, so omitting it or sending an empty list removes every validation.
- `warnings` (list of schema.ProvisioningWarning, optional) — Parts of the setup that could not be completed straight away when you saved. The definition is saved and the setup finishes by itself. Absent when there is nothing to report.

## Errors

### 400 Bad Request Error

Bad Request

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 401 Unauthorized Error

Authentication Error

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 409 Conflict Error

Conflict

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 412 Precondition Failed Error

Precondition Failed - the supplied `If-Match` or `If-None-Match` does not hold. Re-read the resource to obtain its current `ETag`.

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 428 Precondition Error

Precondition Required - `If-Match` is mandatory for this request and was not supplied.

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 429 Too Many Requests Error

Too many requests. Rate limit exceeded.

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 503 Service Unavailable Error

Service Unavailable - the request could not be completed right now and nothing was written. Try again shortly.

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

### 500 Server Error

Internal Server Error

- `args` (map from string to string, required)
- `detail` (string, required)
- `errors` (list of schema.ErrorItem, required)
- `instance` (string, required)
- `path` (string, required)
- `reference` (string, required)
- `status` (integer, required)
- `timestamp` (string, required)
- `title` (string, required)
- `type` (string, required)

## Types

### schema.BusinessEventAttribute

- `name` (string, optional) — Name of the attribute, unique within the definition. Account lookups, posting patterns and identification rules refer to attributes by this name.
- `label` (string, optional) — Display label.
- `type` (enum, optional) — Data type of the attribute.
  - Allowed values: `text`, `integer`, `decimal`, `date`
- `role` (enum, optional) — What the attribute is used for. Exactly one attribute must have the role `event_type`, and every node field of the Journal Line Definition must appear as an attribute with the role `node`. At most one attribute may have the role `effective_date`, and it must be a `date`.
  - Allowed values: `event_type`, `node`, `attribute`, `effective_date`
- `source` (enum, optional) — `input` when the value is supplied with the event (the default), or `reference` when Fynapse fills it in from another entity, which requires `sourceReference`.
  - Allowed values: `input`, `reference`
- `sourceReference` (schema.AttributeSourceReference, optional) — Where an attribute that Fynapse fills in takes its value from.

### schema.EntityValidation

A rule that every incoming business event or Journal Line must satisfy. The `type` says which kind of rule it is and what else it carries. A rule applies to every record unless it has a `when` condition, which limits it to the records that satisfy the condition.

- `type`: `MANDATORY` (Mandatory Validation Schema)
  - `attributeName` (string, optional) — The attribute or field that must have a value.
  - `name` (string, optional) — Name of the rule, unique among the validations of the definition.
  - `when` (schema.ValidationCondition, optional) — Limits a rule to the records that satisfy it. A rule without a condition applies to every record.
- `type`: `ENUM` (Enum Validation Schema)
  - `attributeName` (string, optional) — The attribute or field to check.
  - `name` (string, optional) — Name of the rule, unique among the validations of the definition.
  - `values` (list of string, optional) — The accepted values.
  - `when` (schema.ValidationCondition, optional) — Limits a rule to the records that satisfy it. A rule without a condition applies to every record.
- `type`: `LOOKUP` (Lookup Validation Schema)
  - `entity` (string, optional) — Name of the entity the row is looked up in.
  - `name` (string, optional) — Name of the rule, unique among the validations of the definition.
  - `namespace` (string, optional) — Namespace of that entity.
  - `reference` (list of SchemaLookupValidationReferenceItems, optional) — What the row is matched on. Each item compares an attribute of the entity with an attribute of the record, or with a fixed value.
  - `when` (schema.ValidationCondition, optional) — Limits a rule to the records that satisfy it. A rule without a condition applies to every record.

### schema.ProvisioningWarning

A part of the setup that could not be completed straight away. It finishes by itself.

- `entity` (string, optional) — The entity whose setup was deferred.
- `type` (string, optional) — The kind of problem that was reported.
- `detail` (string, optional) — Details of the problem.

### schema.ErrorItem

- `title` (string, required)
- `detail` (string, required)
- `type` (string, required)
- `path` (string, required)
- `args` (map from string to string, required)

### schema.AttributeSourceReference

Where an attribute that Fynapse fills in takes its value from.

- `name` (string, optional) — Name of the entity the value is looked up in.
- `attribute` (string, optional) — Attribute of that entity.

### schema.ValidationCondition

Limits a rule to the records that satisfy it. A rule without a condition applies to every record.

- `logicalOperator` (string, optional) — How the operands combine.
- `operands` (list of SchemaValidationConditionOperandsItems, optional) — The conditions a record must satisfy for the rule to apply.

### SchemaLookupValidationReferenceItems

- `type`: `ATTRIBUTE` (Lookup Attribute Reference Schema)
  - `attributeName` (string, optional) — The attribute or field of the record it must equal.
  - `referenceAttributeName` (string, optional) — Attribute of the entity that is looked up.
- `type`: `CONST` (Lookup Fixed Value Reference Schema)
  - `referenceAttributeName` (string, optional) — Attribute of the entity that is looked up.
  - `value` (string, optional) — The fixed value it must equal.

### SchemaValidationConditionOperandsItems

- `condition`: `notNull` (Has Value Condition Schema)
  - `attributeName` (string, optional) — The attribute or field to check.
- `condition`: `inList` (In List Condition Schema)
  - `attributeName` (string, optional) — The attribute or field to check.
  - `values` (list of string, optional) — The accepted values.

## Examples

### Example 1

**Request**

```json
{}
```

**Response**

```json
{
  "effectiveFrom": "2020-11-25",
  "attributes": [
    {
      "name": "affiliateCode",
      "label": "Affiliate Code",
      "type": "text",
      "role": "attribute",
      "source": "input",
      "sourceReference": {
        "name": "Product",
        "attribute": "productLine"
      }
    }
  ],
  "primaryKeys": [
    "eventType"
  ],
  "validations": [
    {
      "type": "MANDATORY",
      "attributeName": "costCentre",
      "name": "costCentreRequired",
      "when": {
        "logicalOperator": "AND",
        "operands": [
          {
            "condition": "notNull",
            "attributeName": "product"
          }
        ]
      }
    }
  ],
  "warnings": [
    {
      "entity": "string",
      "type": "string",
      "detail": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.fynapse.com/api/v1/configuration/business-event-definition"

payload = {}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.fynapse.com/api/v1/configuration/business-event-definition';
const options = {
  method: 'PUT',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fynapse.com/api/v1/configuration/business-event-definition"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

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

url = URI("https://api.fynapse.com/api/v1/configuration/business-event-definition")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.fynapse.com/api/v1/configuration/business-event-definition")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.fynapse.com/api/v1/configuration/business-event-definition', [
  'body' => '{}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.fynapse.com/api/v1/configuration/business-event-definition");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

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

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fynapse.com/api/v1/configuration/business-event-definition")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```

### Example 2

**Request**

```json
{}
```

**Response**

```json
{
  "effectiveFrom": "2020-11-25",
  "attributes": [
    {
      "name": "affiliateCode",
      "label": "Affiliate Code",
      "type": "text",
      "role": "attribute",
      "source": "input",
      "sourceReference": {
        "name": "Product",
        "attribute": "productLine"
      }
    }
  ],
  "primaryKeys": [
    "eventType"
  ],
  "validations": [
    {
      "type": "MANDATORY",
      "attributeName": "costCentre",
      "name": "costCentreRequired",
      "when": {
        "logicalOperator": "AND",
        "operands": [
          {
            "condition": "notNull",
            "attributeName": "product"
          }
        ]
      }
    }
  ],
  "warnings": [
    {
      "entity": "string",
      "type": "string",
      "detail": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.fynapse.com/api/v1/configuration/business-event-definition"

payload = {}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.fynapse.com/api/v1/configuration/business-event-definition';
const options = {
  method: 'PUT',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fynapse.com/api/v1/configuration/business-event-definition"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

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

url = URI("https://api.fynapse.com/api/v1/configuration/business-event-definition")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.fynapse.com/api/v1/configuration/business-event-definition")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.fynapse.com/api/v1/configuration/business-event-definition', [
  'body' => '{}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.fynapse.com/api/v1/configuration/business-event-definition");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

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

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fynapse.com/api/v1/configuration/business-event-definition")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```