To create a new entity or update an existing one in the AppZen System. This returns the uuid, the unique identifier, for this entity.
If there already exists an entity, with the given id body parameter, then the existing entity will be updated. The status in the response shows as UPDATED. For a newly created entity, the status shows as CREATED.
Request URI
POST https://api.appzen.com/dictionary-data-services/
entity
Header Parameters
Name | Type | Description | Required |
---|---|---|---|
x-api-key | String | The x-api-key provided to authorize the request. | Yes |
customer-id | String | The Customer ID provided to authorize the request. | Yes |
customer-key | String | The Customer Key provided to authorize the request. | Yes |
Body Parameters
Name | Type | Description | Required |
---|---|---|---|
entity_id |
String |
The unique id for the entity in your System. |
Yes |
entity_name |
String |
The entity name used in your System like the name of the Company or Operating Unit name. |
Yes |
parent_entity_id |
String |
The parent entity id in your System in case this entity is a child entity. |
No *Required if not a top organization |
entity_type |
String |
The type of the entity as defined in your system |
Yes |
appzen_entity_type |
String |
A value for AppZen to understand an entity. |
Yes |
entity_alias_name |
Array |
All the alias names that refer to this entity. |
No |
addresses |
N/A |
The root element for the addresses. |
Yes |
address_type |
String |
This field tells about the type of address. |
Yes |
address |
String |
This is the root element for an address. |
No |
address_line1 |
String |
Line 1 of the address of the entity. |
Yes |
address_line2 |
String |
Line 2 of the address of the entity. |
No |
address_line3 |
String |
Line 3 of the address of the entity. |
No |
area_code |
String |
The area code. |
No |
city |
String |
City in the address of the entity. Example: San Francisco |
No |
company |
String |
Name of the Company of the entity. |
No |
contact |
String |
Name of the contact person for the entity. |
No |
country |
String |
Country name in the address of the entity. |
Yes |
country_iso3 |
String |
Country name in the address in iso3 format. |
No |
|
String |
Email Id of the contact person of the entity. |
No |
phone |
String |
Phone number of the contact person of the entity. |
No |
province |
String |
The name of the Province if it exists in the address. |
No |
state |
String |
The name of the state if it exists in the address. |
No |
zip |
String |
The Zip code of the address. |
No |
site_id |
String |
This is the address reference Id in source ERP of the address of the Company / Operating Unit / Legal Entity. |
No |
site_name |
String |
One entity can have multiple sites so those names should come here. |
No |
custom_json |
String |
For storing any custom key-value pairs needed by your system. |
No |
currency |
String |
This is the default currency associated to this entity. It is the operating currency of the operating unit / legal entity / company |
Yes |
coa_structure |
|
This is case sensitive list of chart of account structure. It should be in the same sequence as gl-code in your system. example:List [ "Entity", "Department", "Line of Business", "Future1" ] |
No |
appzen_coa_structure |
|
Refers to the AppZen mapped values. Please provide the mapped values in the same sequence as the customer coa_structure. OTHER_SEGMENT should be used to map any customer segment type that does not have correspondence with one of the named appzen segment types (e.g. ACCOUNT_SEGMENT, DEPARTMENT_SEGMENT etc). Multiple OTHER_SEGMENT mappings may be specified if needed. |
No |
dataset_lookup_names |
|
One-to-one mapping with coa_structure fields to specify optional lookup contexts. |
No |
coa-look-names |
|
If “” or " " (white space only, no lookup context is specified for the corresponding coa_structure element. |
No |
optional_segments |
list |
This is case sensitive list of items from coa_structure that are optional. |
No |
is_active |
Boolean |
To check if the entity is active in the ERP system. True/False. Default: true |
No |
valid_start_date |
String |
The valid start date of an entity. Date should be in UTC format. |
No |
valid_end_date |
String |
The valid end date of an entity. Date should be in UTC format. |
No |
created_date |
String |
The date when the entity was created. Date should be in UTC format |
No |
updated_date |
String |
The date when the entity was updated. Date should be in UTC format. |
No |
payment_term_id |
String |
The value of the payment term ID associated with this entity. |
No |
custom_json |
N/A |
For storing any custom key-value pairs needed by your system. |
No |
bu_id |
N/A |
The organization id for the default Business / Operating Unit. |
No |
bu_name |
N/A |
The Default Business Unit / Operating Unit for the Legal Entity. |
No |
Sample Request
curl -X POST "https://api.appzen.com/dictionary-data-services/entity"
-H "accept: application/json"
-H "x-api-key: R7wsFxxxx"
-H "customer-id: 1004xxxx"
-H "customer-key: 15d1xxxx"
-H "Content-Type: application/json"
-d "{
{
"entity_id": "string",
"entity_name": "string",
"parent_entity_id": "string",
"entity_type": "string",
"appzen_entity_type": "LEGAL_ENTITY",
"entity_alias_name": [
null
],
"addresses": [
{
"address_type": "REMIT_TO",
"address": {
"address_line1": "12345 MARKET STREET",
"address_line2": "SUITE 1234",
"address_line3": "",
"area_code": "415",
"city": "SAN FRANCISCO",
"company": "Preferred Supplier Inc.",
"contact": "Jane Doe",
"country": "US",
"country_iso3": "USA",
"email": "janedoe@supplier.com",
"phone": "4042965282",
"province": "",
"state": "CA",
"zip": "94016"
},
"site_id": "913838",
"site_name": "California HQ",
"custom_json": {
"key1": "value1"
}
}
],
"currency": "string",
"coa_structure": [
"Entity",
"Department",
"Line of Business",
"Future1"
],
"appzen_coa_structure": [
"LEGAL_ENTITY_SEGMENT",
"DEPARTMENT_SEGMENT",
"OTHER_SEGMENT",
"OTHER_SEGMENT"
],
"dataset_lookup_names": {
"coa-look-names": [
"us_lookups",
"",
" ",
"f1_list"
]
},
"optional_segments": [
"Department",
"Future1"
],
"is_active": true,
"valid_start_date": "2020-11-01T11:01:00Z",
"valid_end_date": "2020-11-01T11:01:00Z",
"created_date": "2020-11-01T11:01:00Z",
"updated_date": "2020-11-01T11:01:00Z",
"payment_term_id": "string",
"custom_json": {
"bu_id": 382,
"bu_name": "HR"
}
}
}"
Sample Response
Success
{
"uuid": "5fc03087-d265-11e7-b8c6-83e29cd24f4c",
"status": "CREATED"
}
Failure
The request fails if you enter an invalid URL.
{
"timestamp": "2019-01-17T16:12:45.977+0000",
"status": 404,
"error": "Not Found",
"message": "Error code : 17e3338d - The resource you specified cannot be not found"
}
Response Code
Response Code | Description |
200 | The request is successful. |
201 |
The request is successful. |
400 |
The request failed due to a malformed request syntax. Check the requested URL, including the parameters. |
401 |
The request failed due to an authorization issue. For example, the Customer Key could be missing or invalid. |
403 |
The request failed due to a permission issue. The x-api key may not have permission to perform the request. |
404 |
The request failed as the resource is not found. Check the requested URL. |
500 |
The request failed due to an AppZen server issue. |
See Also
Comments
Article is closed for comments.