Organizations API

Use the Organizations API to create, retrieve, update, and delete Organizations.

Refer to Organizations API on the Requests and Responses page for more information about the parameters.

Create an Organization

POST /v1/organizations

Use this endpoint to create an Organization and register on the Midaz platform. You can create several Organizations. However, you must create one Organization at a time.

parentOrganizationId field

The parentOrganizationId field is optional and can be used in two different scenarios:

• If the organization needs to be linked to an existing one, populate it with the ID of the "parent" organization obtained from the response of the previously created organization.

• The field is unnecessary if you are creating an organization without a parent.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
  "legalName": "Empresa Teste Ltda",
  "parentOrganizationId": null, //optional
  "doingBusinessAs": "Empresa Teste", //optional
  "legalDocument": "86820799000188",
  "status": { //optional, default status.code = ACTIVE and description = null
    "code": "ACTIVE",
    "description": null
  },
  "address": {
    "line1": "Rua Botucatu, 10",
    "line2": "Casa B",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR" //according to ISO 3166-1 alpha2
  },
  "metadata": {
    "key": "value"
  }
}

Response codes

201

{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": null, //optional
  "legalName": "Empresa Teste Ltda",
  "doingBusinessAs": "Empresa Teste", //optional
  "legalDocument": "86820799000188",
  "address": {
    "line1": "Rua Botucatu, 10",
    "line2": "Casa B",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null,
  "metadata": {
    "key": "value"
  }   
}

400

{
   "code":"0009",
   "title":"Missing Fields in Request",
   "message":"Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request."
}

400

{
   "code":"0032",
   "title":"Invalid Country Code",
   "message":"The provided country code in the 'address.country' field does not conform to the ISO-3166 alpha-2 standard. Please provide a valid alpha-2 country code."
}

---

Retrieve all Organizations

GET /v1/organizations

Use this endpoint to retrieve the information of all Organizations you have created.

If an organization has been deleted, the information of the organization will be displayed, including the date when the deletion occurred in the deletedAt field.

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

[
   {
      "id":"cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
      "parentOrganizationId":null,
      "legalName":"Empresa Teste Ltda",
      "doingBusinessAs":"Empresa Teste",
      "legalDocument":"86820799000188",
      "address":{
         "line1":"Rua Botucatu, 10",
         "line2":"Casa B",
         "zipCode":"04023060",
         "city":"São Paulo",
         "state":"SP",
         "country":"BR"
      },
      "metadata":null,
      "status":{
         "code":"ACTIVE",
         "description":null
      },
      "createdAt":"2024-02-08T16:59:31+0300",
      "updatedAt":"2024-02-08T16:59:31+0300",
      "deletedAt":null
   },
   {
      "id":"5ec9169f-2658-4ee6-8378-52d3bfb10c47",
      "parentOrganizationId":"cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
      "legalName":"Empresa Teste 2 Ltda",
      "doingBusinessAs":"Empresa 2",
      "legalDocument":"98712163000103",
      "address":{
         "line1":"Avenida Brasil, 22",
         "line2":null,
         "zipCode":"12345000",
         "city":"São Paulo",
         "state":"SP",
         "country":"BR"
      },
      "metadata":null,
      "status":{
         "code":"ACTIVE",
         "description":null
      },
      "createdAt":"2024-02-12T13:59:31+0300",
      "updatedAt":"2024-02-12T13:59:31+0300",
      "deletedAt":null
   },
   {
      "id":"9cc00841-602c-4692-a18b-0023fde5e97f",
      "parentOrganizationId":"cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
      "legalName":"Test Deleted Company Ltda",
      "doingBusinessAs":"Deleted Company",
      "legalDocument":"70296969000137",
      "address":{
         "line1": "2375 Victory Ave",
         "line2": null,
         "zipCode": "75202",
         "city": "Dallas",
         "state": "TX",
         "country": "US" 
      },
      "metadata":null,
      "status":{
         "code":"INACTIVE",
         "description":"Blocked on 2024-04-14"
      },
      "createdAt":"2024-02-12T13:59:31+0300",
      "updatedAt":"2024-02-12T13:59:31+0300",
      "deletedAt":"2024-09-30T14:35:18+5401",
   }
]

---

Retrieve Organization by id

GET /v1/organizations/{{organization_id}}

Use this endpoint to retrieve the information of a specific Organization using the identifier (id).

Headers

Name	Value
Authorization	Bearer <token>

Response codes

If an organization has been deleted, the information of the organization will be displayed, including the date when the deletion occurred in the deletedAt field.

200

{
   "id":"cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
   "parentOrganizationId":null,
   "legalName":"Empresa Teste Ltda",
   "doingBusinessAs":"Empresa Teste",
   "legalDocument":"86820799000188",
   "address":{
      "line1":"Rua Botucatu, 10",
      "line2":"Casa B",
      "zipCode":"04023060",
      "city":"São Paulo",
      "state":"SP",
      "country":"BR"
   },
   "metadata":null,
   "status":{
      "code":"ACTIVE",
      "description":null
   },
   "createdAt":"2024-02-08T16:59:31+0300",
   "updatedAt":"2024-02-08T16:59:31+0300",
   "deletedAt":null
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Update an Organization

PATCH /v1/organizations/{{organization_id}}

Use this endpoint to edit and update the information of a specific Organization. When you update an Organization, the following fields can be edited:

• legalName

• parentOganizationId

• doingBusinessAs

• address

• status

• metadata

When updating the metadata object, all previous key-value pairs must be included in the update, or they will be removed. Check the Metadata section for more information.

For compliance reasons, the "legalDocument" field cannot be updated once the Organization has been created.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
   "legalName":"Empresa Teste Ltda",
   "parentOrganizationId": null,
   "doingBusinessAs":"Empresa Teste",//optional
   "address":{
      "line1":"Rua Botucatu, 10",
      "line2":"Casa B",
      "zipCode":"04023060",
      "city":"São Paulo",
      "state":"SP",
      "country":"BR" //according to ISO 3166-1 alpha2
   },
   "status":{
      "code":"MY_CODE",
      "description":"MY_DESCRIPTION"
   }
}

Response codes

200

{
   "id":"cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
   "parentOrganizationId":null,
   "legalName":"Empresa Teste Ltda",
   "doingBusinessAs":"Empresa Teste", //optional
   "legalDocument":"86820799000188",
   "address":{
      "line1":"Rua Botucatu, 10",
      "line2":"Casa B",
      "zipCode":"04023060",
      "city":"São Paulo",
      "state":"SP",
      "country":"BR" 
   },
   "metadata":null,
   "status":{
      "code":"MY_CODE",
      "description":"MY_DESCRIPTION"
   },
   "createdAt":"2024-02-08T16:59:31+0300",
   "updatedAt":"2024-02-08T16:59:31+0300",
   "deletedAt":null
}

400

{
   "code":"0006",
   "title":"Unmodifiable Field Error",
   "message":"Your request includes a field that cannot be modified. Please review your request and try again, removing any uneditable fields. Please refer to the documentation for guidance."
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Delete an Organization

DELETE /v1/organizations/{{organization_id}}

Use this endpoint to deactivate an Organization.

Headers

Name	Value
Authorization	Bearer <token>

Response codes

204

400

{
   "code":"0008",
   "title":"Action Not Permitted",
   "message":"The action you are attempting is not allowed in the current environment. Please refer to the documentation for guidance."
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---