> ## Documentation Index > Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt > Use this file to discover all available pages before exploring further. # Create automation > Create a new recurring investment or savings automation with automatic mandate management. ## OpenAPI ````yaml POST /automations openapi: 3.0.3 info: title: Wealthyhood Automations API version: 1.0.0 description: > Recurring investment automation endpoints for Wealthyhood portfolios. All requests use machine-to-machine (M2M) authentication. Each request requires: - A bearer access token (M2M token with required scopes) - An `x-user-id` header to specify which user's data to access **Note:** Only `TopUpAutomation` (recurring investments) and `SavingsTopUpAutomation` (recurring savings top-ups) are currently supported in the API. servers: - url: https://{host} variables: host: default: api.wealthyhood.com description: Wealthyhood API host name. security: - bearerAuth: [] tags: - name: Automations description: Manage recurring investment automations for users. paths: /automations: post: tags: - Automations summary: Create an automation description: > Create a new recurring investment automation for the authenticated user. The automation will set up direct debit payments from the specified bank account on the chosen day of each month. **Key behaviors:** - If no mandate exists for the bank account, one will be created automatically - If a mandate exists but is in a failed/cancelled state, a new one will be created - If a mandate exists and is active or pending, it will be reused - Both `TopUpAutomation` and `SavingsTopUpAutomation` categories are supported parameters: - $ref: '#/components/parameters/XUserId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAutomationRequest' examples: topUpAutomation: summary: Recurring investment automation value: category: TopUpAutomation bankAccountId: 7501d8537fb3fc001234ijkl orderAmount: 100 dayOfMonth: 15 savingsTopUpAutomation: summary: Recurring savings top-up automation value: category: SavingsTopUpAutomation bankAccountId: 7501d8537fb3fc001234ijkl orderAmount: 50 dayOfMonth: 1 responses: '201': description: Automation created successfully content: application/json: schema: $ref: '#/components/schemas/Automation' examples: topUpAutomation: summary: TopUpAutomation response value: id: 7501d8537fb3fc001234abcd category: TopUpAutomation status: Active frequency: monthly dayOfMonth: 15 currency: EUR amount: 100 allocationMethod: holdings mandate: id: 7501d8537fb3fc001234efgh status: Pending bankAccountId: 7501d8537fb3fc001234ijkl savingsTopUpAutomation: summary: SavingsTopUpAutomation response value: id: 7501d8537fb3fc001234mnop category: SavingsTopUpAutomation status: Active frequency: monthly dayOfMonth: 1 currency: EUR amount: 50 savingsProduct: mmf_dist_eur mandate: id: 7501d8537fb3fc001234qrst status: Pending bankAccountId: 7501d8537fb3fc001234ijkl '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' components: parameters: XUserId: name: x-user-id in: header required: true description: >- User identifier for the M2M client to specify which user's data to access. schema: type: string pattern: ^[a-f0-9]{24}$ schemas: CreateAutomationRequest: type: object required: - category - bankAccountId - orderAmount - dayOfMonth properties: category: type: string description: > Type of automation to create. Supports: - `TopUpAutomation`: Recurring investments into the user's investment portfolio - `SavingsTopUpAutomation`: Recurring top-ups into a savings product (money market fund) enum: - TopUpAutomation - SavingsTopUpAutomation bankAccountId: type: string description: > ID of the bank account to use for direct debit payments. A mandate will be created automatically if one doesn't exist. pattern: ^[a-f0-9]{24}$ orderAmount: type: number format: double description: > Amount to invest or save each month in the user's currency. Must be within the allowed minimum and maximum recurring investment limits. minimum: 10 dayOfMonth: type: integer description: > For `SavingsTopUpAutomation`, day of the month when the recurring savings top-up is collected (valid values 1-28 or -1 for last day of the month; 0 is not allowed). For `TopUpAutomation` (recurring investments), this field is optional and ignored. minimum: -1 maximum: 28 Automation: oneOf: - $ref: '#/components/schemas/TopUpAutomation' - $ref: '#/components/schemas/SavingsTopUpAutomation' discriminator: propertyName: category mapping: TopUpAutomation: $ref: '#/components/schemas/TopUpAutomation' SavingsTopUpAutomation: $ref: '#/components/schemas/SavingsTopUpAutomation' TopUpAutomation: type: object required: - id - category - status - frequency - dayOfMonth - currency - amount - allocationMethod - mandate properties: id: type: string description: Automation identifier. category: type: string enum: - TopUpAutomation status: type: string description: | Current status of the automation: - `Active`: Automation is active and will execute on schedule - `Inactive`: Automation has been cancelled - `Pending`: Automation is waiting to be activated enum: - Active - Inactive - Pending frequency: type: string description: >- How often the automation runs. Currently only `monthly` is supported. enum: - monthly dayOfMonth: type: integer description: | Day of the month for recurring investment scheduling. currency: type: string description: ISO 4217 currency code for the recurring investment. amount: type: number format: double description: Amount invested each month. consideration: type: object description: Automation consideration with currency and amount properties: currency: type: string description: ISO 4217 currency code example: EUR enum: - GBP - EUR - USD amount: type: number format: double description: Amount invested each month in major units example: 100 minimum: 0 allocationMethod: type: string description: > How funds are allocated. In B2B, this is always `holdings` (proportional to existing holdings). enum: - holdings mandate: $ref: '#/components/schemas/Mandate' SavingsTopUpAutomation: type: object required: - id - category - status - frequency - dayOfMonth - currency - amount - savingsProduct - mandate properties: id: type: string description: Automation identifier. category: type: string enum: - SavingsTopUpAutomation status: type: string description: | Current status of the automation: - `Active`: Automation is active and will execute on schedule - `Inactive`: Automation has been cancelled - `Pending`: Automation is waiting to be activated enum: - Active - Inactive - Pending frequency: type: string description: >- How often the automation runs. Currently only `monthly` is supported. enum: - monthly dayOfMonth: type: integer description: Day of the month when the recurring savings top-up is collected. currency: type: string description: ISO 4217 currency code for the recurring savings top-up. amount: type: number format: double description: Amount added to savings each month. consideration: type: object description: Automation consideration with currency and amount properties: currency: type: string description: ISO 4217 currency code example: EUR enum: - GBP - EUR - USD amount: type: number format: double description: Amount added to savings each month in major units example: 50 minimum: 0 savingsProduct: type: string description: > The savings product ID where funds are deposited. Currently set to `mmf_dist_eur` (Euro money market fund) for all SavingsTopUpAutomation automations. example: mmf_dist_eur mandate: $ref: '#/components/schemas/Mandate' ApiErrorResponse: type: object properties: status: type: integer error: type: object properties: message: type: string description: type: string nullable: true responseId: type: string format: uuid Mandate: type: object description: Direct debit mandate information linked to the automation. properties: id: type: string description: Mandate identifier. status: type: string description: | Current status of the mandate: - `Pending`: Mandate is being set up with the payment provider - `Active`: Mandate is active and can be used for payments - `Inactive`: Mandate has been cancelled or failed enum: - Pending - Active - Inactive bankAccountId: type: string description: ID of the bank account linked to this mandate. responses: BadRequestError: description: Validation failure or business rule violation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' examples: invalidAmount: summary: Invalid order amount value: status: 400 error: message: You need to invest at least €10.00. description: Operation failed responseId: 7c91c5fe-d5a8-4b82-8e3f-5af2e30e43c2 invalidDayOfMonth: summary: Invalid day of month value: status: 400 error: message: >- Day of month should be between 1 and 28 or set to -1 but instead is 0 description: Operation failed responseId: 8d92c6gf-e6b9-5c93-9f4g-6bg3f41f54d3 UnauthorizedError: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 401 error: message: User not found responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a ForbiddenError: description: Authenticated user cannot act on the requested resource or lacks scopes. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 403 error: message: You do not have access to this bank account responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76 NotFoundError: description: Automation, bank account, or related resource was not found. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 404 error: message: Automation not found responseId: 65c0b1f6-2a48-4c4f-a5aa-9b9c8c6f9b58 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Auth0-issued access token that includes the scopes listed for the endpoint. ````