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.

Headers

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

Request body

{
  "legalName": "Sanchez Tech LTDA",
  "parentOrganizationId": "8cc11bfe-f90f-4a98-ae51-61571f69f75e",
  "doingBusinessAs": "The ledger.io",
  "legalDocument": "48784548000104",
  "address": {
    "line1": "Avenida Paulista, 1234",
    "line2": "CJ 203",
    "zipCode": "04696040",
    "city": "Sao Paulo",
    "state": "SP",
    "country": "BR"
  },
  "status": {
    "code": "ACTIVE", 
    "description": null
  },
  "metadata": {
    "key": "value"
  }
}

Response codes

201

{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": "8cc11bfe-f90f-4a98-ae51-61571f69f75e",
  "legalName": "Sanchez Tech LTDA",
  "doingBusinessAs": "The ledger.io",
  "legalDocument": "48784548000104",
  "address": {
    "line1": "Avenida Paulista, 1234",
    "line2": "CJ 203",
    "zipCode": "04696040",
    "city": "Sao 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
}

400

{
  "code": "0009",
  "title": "Missing Fields in Request",
  "description": "Your request is missing one or more required fields. Please refer to the documentation to verify the necessary fields for your request."
}

---

Retrieve all Organizations

GET /v1/organizations

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

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

[
  {
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "name": "Sanchez Tech LTDA",
    "doingBusinessAs": "The ledger.io",
    "legalDocument": "48784548000104",
    "address": {
      "line1": "Avenida Paulista, 1234",
      "line2": "CJ 203",
      "zipCode": "04696040",
      "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": "96f9ecf6-e8c0-4637-b879-59b9c11d46d8",
    "name": "Another Org",
    "doingBusinessAs": "Fake.io",
    "legalDocument": "98712163000103",
    "address": {
      "line1": "Avenida Brasil, 22",
      "line2": null,
      "zipCode": "12345000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    },
    "metadata": null,
    "status": {
      "code": "INACTIVE",
      "description": "Blocked by Gabriel on 2024-04-14"
    },
    "createdAt": "2024-02-12T13:59:31+0300",
    "updatedAt": "2024-02-12T13:59:31+0300",
    "deletedAt": null
  }
]

---

Retrieve Organization by id

GET /v1/organizations/{{id}}

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

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "name": "Sanchez Tech LTDA",
    "doingBusinessAs": "The ledger.io",
    "legalDocument": "48784548000104",
    "address": {
        "line1": "Avenida Paulista, 1234",
        "line2": "CJ 203",
        "zipCode": "04696040",
        "city": "Sao 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
}

---

Update an Organization

PATCH /v1/organizations/{{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

• doingBusinessAs

• address

• status

• parentOganizationId

• 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": "Sanchez Tech LTDA",
  "parentOrganizationId": "8cc11bfe-f90f-4a98-ae51-61571f69f75e",
  "doingBusinessAs": "The ledger.io",
  "address": {
    "line1": "Avenida Paulista, 1234",
    "line2": "CJ 203",
    "zipCode": "04696040",
    "city": "Sao Paulo",
    "state": "SP",
    "country": "BR"
  },
  "status": {
    "code": "MY_CODE",
    "description": "MY_DESCRIPTION"
  }
}

Response codes

200

{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": "8cc11bfe-f90f-4a98-ae51-61571f69f75e",
  "name": "Sanchez Tech LTDA",
  "doingBusinessAs": "The ledger.io",
  "legalDocument": "48784548000104",
  "address": {
    "line1": "Avenida Paulista, 1234",
    "line2": "CJ 203",
    "zipCode": "04696040",
    "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",
  "description": "Your request contains a field that cannot be modified. Please review your request and try again, removing any fields that cannot be edited. Consult the documentation for guidance."
}

404

{
  "code": "0007",
  "title": "Invalid Script Error",
  "description": "Entity not found."
}

---

Delete an Organization

DELETE /v1/organizations/{{id}}

Use this endpoint to deactivate an Organization.

Headers

Name	Value
Authorization	Bearer <token>

Response codes

204

400

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

404

{
  "code": "0007",
  "title": "Invalid Script Error",
  "description": "Entity not found."
}

---