> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Account

> Create Account



## OpenAPI

````yaml post /api/v1/csp/account
openapi: 3.1.0
info:
  title: Paylias API
  description: >-
    Paylias is a network that enables developers to orchestrate money movement
    between different financial institutions with ease and speed. The Paylias
    API makes it simple for financial platforms to issue virtual addresses,
    manage connections and exchange value by sending and receiving money. Our
    API is based upon REST principles, returns JSON responses, and uses standard
    HTTP response codes.
  version: 0.1.0
  contact: {}
servers:
  - url: https://sandbox.api.paylias.xyz/gateway
security: []
tags:
  - name: API Authentication
    description: >-
      For server-to-server communication, Paylias supports authentication
      through JWT tokens as well as API keys. All APIs that are that deal with
      the `Organization` resource are authenticated using JWT tokens, while the
      rest of the system uses API Keys to authenticate


      To use a JWT token, set the Authorization header to `Bearer`. To use an
      API key, set a header called `X-PAYLIAS-API-KEY` and use the API key as
      the value.


      ## JWT token


      When making requests to Paylias from a browser, you can use JSON Web
      Tokens (JWT). This requires the credentials of a user that has admin
      access. The validity of JWT tokens issued by Paylias is 7 days.


      ## API key


      Longer lasting access tokens can be generated with fine grained
      permissions using the Create API key endpoint. These access tokens can be
      rotated, revoked and updated through the browser as well. API Keys are
      linked to a Namespace to allow finer access controls when dealing with API
      requests using long lived tokens. While account admins can take actions on
      API keys from the dashboard, the `X-Partner-ID` header must be set to the
      id of the Namespace for which the API key was originally issued against.
  - name: Organizations
    description: >-
      In the Paylias network, an `Organization` represents a legal entity,
      specifically a financial institution. It stands at the top of the system's
      hierarchy, overseeing sub-entities like `api keys`, `webhooks`, and
      `partners`.


      Given its financial nature, the Paylias network has certain verification
      processes to fulfill. When users join the Paylias dashboard, they
      initially receive an account in a sandboxed environment. This phase allows
      for familiarization without impacting the main system. Full access is
      granted once a member of the Paylias team validates and completes all
      necessary formalities for the user.


      For efficient management, users can either use the dashboard or APIs, with
      the latter requiring a valid JWT Token for secure interactions.
  - name: Namespace
    description: >-
      A `namespace` is a logical collection of payment addresses that are issued
      by an `organization`. Payment addresses issued inside a `namespace` will
      share a common `domain`. The domain helps identify organizations, country
      of issuance and other specifics around the brand, rewards and
      configurations.
  - name: Accounts
  - name: Validation
  - name: API Keys
    description: >-
      Longer lasting access tokens can be generated with fine grained
      permissions using the Create API key endpoint. These access tokens can be
      rotated, revoked and updated through the browser as well. API Keys are
      linked to a Namespace to allow finer access controls when dealing with API
      requests using long lived tokens. While account admins can take actions on
      API keys from the dashboard, the `X-Partner-ID` header must be set to the
      id of the Namespace for which the API key was originally issued against.
  - name: Webhooks
    description: >-
      Webhooks allow applications to communicate in real-time. When an event
      occurs, a webhook will deliver the event data to the application
      determined by the target endpoint. A webhook can be setup to be notified
      of all event types or specific ones. This allows your application to react
      to events, which is more efficient than polling an API to determine if an
      event has occurred.


      In the Paylias network, webhooks are used to communicate events related to
      Links and Payments.


      Similar to API Keys, Webhooks are created against a Namespace and thus
      require the `X-Partner-ID` header to be set in all requests


      ## Event types


      Here are the event types that we capture and send. This may not be a
      comprehensive list as we are continuing to add events to our system.


      | **Event Identifier** | **Description** |

      | --- | --- |

      | `link.create.resp` | A link request has been processed |

      | `link.propose.req` | A link request has been proposed |

      | `link_established` | A link has been established |

      | `link_update_resp` | A link has been updated |
  - name: Customers
  - name: Payments
  - name: Submissions
  - name: Admissions
  - name: Admission Tasks
  - name: Transactions
  - name: Settlements
    description: Settlement batches, partner merkle artefacts, and settlement net positions
  - name: Exceptions
paths:
  /api/v1/csp/account:
    post:
      tags:
        - Accounts
      summary: Create Account
      description: Create Account
      operationId: createAccount
      parameters:
        - $ref: '#/components/parameters/PartnerIdHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        $ref: '#/components/requestBodies/CreateAccount'
      responses:
        '200':
          $ref: '#/components/responses/AccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
components:
  parameters:
    PartnerIdHeader:
      name: x-partner-id
      in: header
      required: true
      schema:
        type: string
        default: ''
      description: The Partner ID header used for authorization
    IdempotencyKeyHeader:
      name: idempotency-key
      in: header
      required: true
      schema:
        type: string
        default: ''
      description: The Idempotency Key - usually a UUID
  requestBodies:
    CreateAccount:
      description: Request to create a new account
      content:
        application/json:
          schema:
            type: object
            properties:
              account_number:
                type: string
                example: '1234567890123456'
                description: Account number
              account_title:
                type: string
                example: John Doe
                description: Title of the account
              routing_number:
                type: string
                example: '123456789'
                description: Routing number of the account
              type:
                type: string
                enum:
                  - AT_Checkings
                  - AT_Savings
                example: AT_Checkings
                description: Type of the account
            required:
              - account_number
              - account_title
              - routing_number
              - type
          examples:
            Create Account:
              value:
                account_number: '1234567890123456'
                account_title: John Doe
                routing_number: '123456789'
                type: AT_Checkings
  responses:
    AccountResponse:
      description: Response when retrieving an account
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
        X-Csp-Version:
          $ref: '#/components/headers/CspVersionHeader'
        X-Partner-Id:
          $ref: '#/components/headers/PartnerIdHeader'
        X-Org-Id:
          $ref: '#/components/headers/OrgIdHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StandardResponse'
              - type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Account'
          examples:
            success:
              value:
                data:
                  account_title: John Doe
                  created_at:
                    seconds: 1635784800
                  masked_account_number: XXXX-XXXX-XXXX-1234
                  partner_id: part_123456789
                  routing_number: '123456789'
                  status: active
                  token: acct_123456789
                  type: checking
                  updated_at:
                    seconds: 1635788400
                  institution:
                    address:
                      address: 123 Main St
                      city: New York
                      postal_code: '10001'
                      state: NY
                    name: Example Bank
                    phone_number: '+1234567890'
                    routing_number: '123456789'
                ok: true
    BadRequest:
      description: Bad request
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
        X-Csp-Version:
          $ref: '#/components/headers/CspVersionHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - type: object
                properties:
                  code:
                    example: error.bad_request
                  message:
                    example: Invalid request parameters
    Unauthorized:
      description: Unauthorized
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
        X-Csp-Version:
          $ref: '#/components/headers/CspVersionHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - type: object
                properties:
                  code:
                    example: error.unauthorized
                  message:
                    example: Authentication required
  headers:
    ContentLengthHeader:
      schema:
        type: string
        example: '256'
    DateHeader:
      schema:
        type: string
        example: Sat, 12 Aug 2023 08:55:04 GMT
    CspVersionHeader:
      schema:
        type: string
        example: gateway-csp/v1.0.0
    PartnerIdHeader:
      schema:
        type: string
        example: part_123456789
    OrgIdHeader:
      schema:
        type: string
        example: org_123456789
  schemas:
    StandardResponse:
      type: object
      description: Standard response structure for successful operations
      properties:
        ok:
          type: boolean
          example: true
          description: Indicates if the operation was successful
        data:
          type: object
          description: Contains the response data
    Account:
      type: object
      description: Account information
      properties:
        account_title:
          type: string
          example: John Doe
          description: Title of the account
        created_at:
          $ref: '#/components/schemas/Timestamp'
        masked_account_number:
          type: string
          example: XXXX-XXXX-XXXX-1234
          description: Masked account number
        partner_id:
          type: string
          example: part_123456789
          description: ID of the partner the account belongs to
        routing_number:
          type: string
          example: '123456789'
          description: Routing number of the account
        status:
          type: string
          example: active
          description: Status of the account
        token:
          type: string
          example: acct_123456789
          description: Account identifier token
        type:
          type: string
          example: checking
          description: Type of the account
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        institution:
          type: object
          description: Institution information
          properties:
            address:
              type: object
              properties:
                address:
                  type: string
                  example: 123 Main St
                city:
                  type: string
                  example: New York
                postal_code:
                  type: string
                  example: '10001'
                state:
                  type: string
                  example: NY
            name:
              type: string
              example: Example Bank
            phone_number:
              type: string
              example: '+1234567890'
            routing_number:
              type: string
              example: '123456789'
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        code:
          type: string
          description: Error code identifying the type of error
        message:
          type: string
          description: Human-readable error message
    Timestamp:
      type: object
      description: A timestamp with seconds since epoch
      properties:
        seconds:
          type: number
          format: int64
          example: 1691831179
          description: Time in seconds since epoch
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````