View as Markdown

Clients

Data model

JSON:API resource type: client.

namestring

Display name of the client. Required.

Relationships

childrenarray of client

Clients owned by the client itself.

legalEntitiesarray of legal-entity

Legal entities owned by the client.

parentclient

The parent client that owns the client displayed. A client without a parent has no parent member in relationships.

reportingEntitiesarray of reporting-entity

Reporting entities owned by the client.

GET/api/v2/clients

List clients

Fetch all clients the caller has access to. Returns 200.

Request
GET/api/v2/clients
curl https://api.aleta.ai/api/v2/clients \
  -H "Authorization: Bearer {access_token}"
Response
{
  "data": [
    {
      "id": "66fd6003218be3af85e088f7",
      "type": "client",
      "attributes": {
        "name": "Top-level client"
      },
      "relationships": {
        "children": {
          "data": [
            { "type": "client", "id": "666be3f97fc417debcea6a5e" },
            { "type": "client", "id": "7a2f4b8c9d1e3f5a6b7c8d9e" }
          ]
        },
        "legalEntities": {
          "data": []
        },
        "reportingEntities": {
          "data": []
        }
      }
    },
    {
      "id": "666be3f97fc417debcea6a5e",
      "type": "client",
      "attributes": {
        "name": "Child client 1"
      },
      "relationships": {
        "children": {
          "data": []
        },
        "legalEntities": {
          "data": [
            { "type": "legal-entity", "id": "13a05f02a8adba3eac99cc34" }
          ]
        },
        "parent": {
          "data": { "type": "client", "id": "66fd6003218be3af85e088f7" }
        },
        "reportingEntities": {
          "data": [
            { "type": "reporting-entity", "id": "cbdebdf8d547d3fbb8aac6fb" }
          ]
        }
      }
    },
    {
      "id": "7a2f4b8c9d1e3f5a6b7c8d9e",
      "type": "client",
      "attributes": {
        "name": "Child client 2"
      },
      "relationships": {
        "children": {
          "data": []
        },
        "legalEntities": {
          "data": [
            { "type": "legal-entity", "id": "13a05f02a8adba3eac99cc34" }
          ]
        },
        "parent": {
          "data": { "type": "client", "id": "66fd6003218be3af85e088f7" }
        },
        "reportingEntities": {
          "data": [
            { "type": "reporting-entity", "id": "d3e4f5a6b7c8d9e0f1a2b3c4" }
          ]
        }
      }
    },
    {
      "id": "eead576c7faa2fef6ed8031b",
      "type": "client",
      "attributes": {
        "name": "Client name 2"
      },
      "relationships": {
        "children": {
          "data": []
        },
        "legalEntities": {
          "data": [
            { "type": "legal-entity", "id": "f050f9bea3ffcffbc9ee3fbb" }
          ]
        },
        "parent": {
          "data": { "type": "client", "id": "786be3f97fc417debcea3214" }
        },
        "reportingEntities": {
          "data": [
            { "type": "reporting-entity", "id": "faa96fb2fdb65396cfc69f93" }
          ]
        }
      }
    }
  ]
}
POST/api/v2/clients

Create a client

Create a new client. Returns 201. The client gets its own release group, named {uuid} (Generated by ExternalApi).

data.type must be client; another type is refused with 409.

Attributes

namestring

Display name of the client. Required.

Relationships

parentclient

The client that owns the new client. Required: a request without it is refused with 400. A parent ID that is not a 24-character hexadecimal ID is refused with 404.

Request
POST/api/v2/clients
curl -X POST https://api.aleta.ai/api/v2/clients \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "client",
      "attributes": {
        "name": "New client name"
      },
      "relationships": {
        "parent": {
          "data": { "type": "client", "id": "666be3f97fc417debcea6a5e" }
        }
      }
    }
  }'
Response
{
  "data": {
    "id": "669919f890e4517165d07eb8",
    "type": "client",
    "attributes": {
      "name": "New client name"
    },
    "relationships": {
      "children": {
        "data": []
      },
      "parent": {
        "data": { "type": "client", "id": "666be3f97fc417debcea6a5e" }
      },
      "legalEntities": {
        "data": []
      },
      "reportingEntities": {
        "data": []
      }
    }
  }
}
GET/api/v2/clients/{id}

Retrieve a client

Find a client with a specific id. Returns 200, or 404 when no client with that id is visible to the caller.

Path parameters

idstring

ID of the client to look up: a 24-character hexadecimal ID. Required. Any other format is refused with 400.

Request
GET/api/v2/clients/{id}
curl https://api.aleta.ai/api/v2/clients/66fd6003218be3af85e088f7 \
  -H "Authorization: Bearer {access_token}"
Response
{
  "data": {
    "id": "66fd6003218be3af85e088f7",
    "type": "client",
    "attributes": {
      "name": "Top-level client"
    },
    "relationships": {
      "children": {
        "data": [
          { "type": "client", "id": "666be3f97fc417debcea6a5e" },
          { "type": "client", "id": "666be3f97fc417debcea6a5f" }
        ]
      },
      "legalEntities": {
        "data": []
      },
      "reportingEntities": {
        "data": []
      }
    }
  }
}
DELETE/api/v2/clients/{id}

Delete a client

Delete the client given by id. Returns 204 with no body.

A client without a parent cannot be deleted (400). A client that still owns child clients, legal entities or reporting entities is refused with 400; delete those first. An unknown id returns 404.

The release group created with the client is not deleted with it, as on the legacy platform.

Path parameters

idstring

Client identifier, see GET /clients. Required.

Request
DELETE/api/v2/clients/{id}
curl -X DELETE https://api.aleta.ai/api/v2/clients/4dbeb1d24abafb4fa8fca7e8 \
  -H "Authorization: Bearer {access_token}"
PATCH/api/v2/clients/{id}

Update a client

Update the client given by id. Returns 204 with no body. An unknown id returns 404.

attributes must be present. Relationships cannot be changed: a request with any relationship is refused with 400.

Path parameters

idstring

Client identifier, see GET /clients. Required.

Attributes

namestring

Optional. New display name of the client. Omit it or send null to keep the current name. An empty string is refused with 400.

Request
PATCH/api/v2/clients/{id}
curl -X PATCH https://api.aleta.ai/api/v2/clients/12ce0ffdacda14f9fcd0afd8 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "12ce0ffdacda14f9fcd0afd8",
      "type": "client",
      "attributes": {
        "name": "Updated client name"
      }
    }
  }'