Create or Update an Entity

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. 
This can be LEGAL_ENTITY, OTHER_ENTITY, COMPANY

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. 
Example: US

Yes

country_iso3

String

Country name in the address in iso3 format.
Example: USA

No

email

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.

Example:List [ "LEGAL_ENTITY_SEGMENT", "DEPARTMENT_SEGMENT", "OTHER_SEGMENT", "OTHER_SEGMENT" ]

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.
Example:List [ "us_lookups", "", " ", "f1_list" ]

No

optional_segments

list

This is case sensitive list of items from coa_structure that are optional.
Example: List [ "Department", "Future1" ]

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.
example:2020-11-01T11:01:00Z

No

valid_end_date

String

The valid end date of an entity.

Date should be in UTC format.
example:2020-11-01T11:01:00Z

No

created_date

String

The date when the entity was created.

Date should be in UTC format
example:2020-11-01T11:01:00Z

No

updated_date

String

The date when the entity was updated.

Date should be in UTC format.
example:2020-11-01T11:01:00Z

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

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.