Agicap Manage beneficiaries API
The Manage beneficiaries API from Agicap — 4 operation(s) for manage beneficiaries.
OpenAPI Specification
openapi: 3.0.0
info:
contact: {}
title: Clients AR Account reports Manage beneficiaries API
version: v1
servers:
- url: https://api.agicap.com
- url: https://api.agicap.internal
tags:
- name: Manage beneficiaries
paths:
/public/payments/v2/entities/{entityId}/Beneficiaries:
delete:
description: Delete all beneficiaries from the specific entity
operationId: 5_Beneficiaries_Delete_All
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
responses:
'204':
content:
text/plain: {}
description: All beneficiaries have been successfully deleted.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Delete all beneficiaries
tags:
- Manage beneficiaries
get:
description: List all existing beneficiaries in the entity, and their detailed information.
operationId: 1_Beneficiaries_Get_All
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiaryPresentation'
type: array
description: Your request has been successfully processed.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Get beneficiaries
tags:
- Manage beneficiaries
post:
description: Create a beneficiary in a specific entity with its detailed information.
operationId: 2_Beneficiaries_Add
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
requestBody:
content:
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.AddBeneficiaryDto'
description: Beneficiary's information to add
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.AddBeneficiaryDto'
description: Beneficiary's information to add
text/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.AddBeneficiaryDto'
description: Beneficiary's information to add
required: true
responses:
'201':
content:
text/plain: {}
description: The beneficiary has been successfully added.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Create a beneficiary
tags:
- Manage beneficiaries
/public/payments/v2/entities/{entityId}/Beneficiaries/sync:
post:
description: 'Start an asynchronous bulk synchronization of beneficiaries from your ERP. Each item is upserted using its ERP identifier (`erpId`) as the key: an existing beneficiary is updated, otherwise a new one is created.
The synchronization is additive: beneficiaries absent from the payload are not deleted (use the delete endpoint to remove one).
Processing runs in the background; the returned sync identifier lets you poll the synchronization report.'
operationId: 6_Beneficiaries_Sync_Start
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
requestBody:
content:
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.StartBeneficiarySyncDto'
description: Payload of a beneficiary synchronization request.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.StartBeneficiarySyncDto'
description: Payload of a beneficiary synchronization request.
text/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.StartBeneficiarySyncDto'
description: Payload of a beneficiary synchronization request.
required: true
responses:
'202':
content:
text/plain: {}
description: The beneficiary synchronization has been accepted and is being processed.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Synchronize beneficiaries
tags:
- Manage beneficiaries
/public/payments/v2/entities/{entityId}/Beneficiaries/sync/{syncId}:
get:
description: Retrieve the status and the per-item errors of a beneficiary synchronization, using the sync identifier returned by the synchronize beneficiaries endpoint.
operationId: 7_Beneficiaries_Sync_Report
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
- description: Identifier of the synchronization. This ID is obtained using the synchronize beneficiaries endpoint
example: 1660e6c3-54fd-402f-be8e-7748efd94791
in: path
name: syncId
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncReportPresentation'
description: Your request has been successfully processed.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: No synchronization was found for the provided sync identifier.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Get a beneficiary synchronization report
tags:
- Manage beneficiaries
/public/payments/v2/entities/{entityId}/Beneficiaries/{beneficiaryId}:
delete:
description: Delete a beneficiary from a specific entity, using its identifier (obtained via the get beneficiaries endpoint)
operationId: 4_Beneficiaries_Delete
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
- description: Identifier of the beneficiary in Agicap. This ID is obtained using get beneficiaries endpoint
example: 1660e6c3-54fd-402f-be8e-7748efd94791
in: path
name: beneficiaryId
required: true
schema:
format: uuid
type: string
responses:
'204':
content:
text/plain: {}
description: The beneficiary has been successfully deleted.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Delete a beneficiary
tags:
- Manage beneficiaries
put:
description: Edit a beneficiary from a specific entity with its detailed information, using its identifier (obtained via the get beneficiaries endpoint)
operationId: 3_Beneficiaries_edit
parameters:
- description: Agicap entity identifier
example: 123456
in: path
name: entityId
required: true
schema:
format: int32
type: integer
- description: Identifier of the beneficiary in Agicap. This ID is obtained using get beneficiaries endpoint
example: 1660e6c3-54fd-402f-be8e-7748efd94791
in: path
name: beneficiaryId
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.EditBeneficiaryDto'
description: Beneficiary's information to edit
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.EditBeneficiaryDto'
description: Beneficiary's information to edit
text/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.EditBeneficiaryDto'
description: Beneficiary's information to edit
required: true
responses:
'204':
content:
text/plain: {}
description: The beneficiary has been successfully edited.
'401':
description: Unauthorized request.
'403':
description: Forbidden request.
'429':
description: Too many requests. Please try again later.
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
description: An internal server occurred.
security:
- bearer_client_credentials:
- public-api:manage-payment-beneficiaries
- agicap:public-api
- bearerAuth: []
summary: Edit a beneficiary
tags:
- Manage beneficiaries
components:
schemas:
PaymentsPreparation.Web.Models.Presentations.Beneficiary.PostalAddressPresentation:
additionalProperties: false
properties:
city:
type: string
country:
type: string
number:
nullable: true
type: string
state:
nullable: true
type: string
streetName:
type: string
zipCode:
nullable: true
type: string
required:
- city
- country
- streetName
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.PostalAddressDto:
additionalProperties: false
description: Information about the postal address of the beneficiary
properties:
city:
description: Name of the city - required if any field of the address is filled
example: Paris
type: string
country:
description: Country in which the beneficiary is located - 2 characters ISO 3166 code - required if any field of the address is filled
example: France
type: string
number:
description: Number of the building
example: '42'
nullable: true
type: string
state:
description: State in which the beneficiary is located if needed
nullable: true
type: string
streetName:
description: Name of the street - required if any field of the address is filled
example: Av. des Champs-Élysées
type: string
zipCode:
description: ZIP code of the beneficiary location if needed
example: '75008'
nullable: true
type: string
required:
- city
- country
- streetName
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncErrorCodePresentation:
description: 'Reason an item failed during a beneficiary synchronization. Each value is contractual: renaming one is a breaking change.'
enum:
- InvalidName
- InvalidIban
- InvalidBic
- InvalidBankIdentifier
- InvalidLocalClearingCode
- InvalidCountry
- UnsupportedCountry
- MissingBankCountry
- IncompletePostalAddress
- NameAlreadyUsed
- AccountNumberAlreadyUsed
- NameAndAccountNumberAlreadyUsed
- SupplierNotFound
type: string
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiaryPresentation:
additionalProperties: false
properties:
bankAccount:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BankAccountPresentation'
companyLegalIdentifier:
nullable: true
type: string
id:
format: uuid
type: string
name:
type: string
postalAddress:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.PostalAddressPresentation'
nullable: true
uncertaintyStatus:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.UncertaintyStatusPresentation'
nullable: true
validationStatus:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.ValidationStatusPresentation'
nullable: true
required:
- bankAccount
- id
- name
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.AddBeneficiaryDto:
additionalProperties: false
description: Beneficiary's information to add
properties:
bankAccount:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BankAccountDto'
description: Information about the bank account of the beneficiary
nullable: true
name:
description: Name of the beneficiary
type: string
postalAddress:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.PostalAddressDto'
description: Information about the postal address of the beneficiary
nullable: true
required:
- name
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.ValidationStatusPresentation:
enum:
- Validated
- PendingValidation
type: string
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncReportPresentation:
additionalProperties: false
description: Status and per-item errors of a beneficiary synchronization.
properties:
createdAt:
description: Date and time the synchronization was started (ISO 8601, UTC).
example: '2026-06-09T14:30:00+00:00'
format: date-time
type: string
errors:
description: Per-item errors. Empty when every item was synchronized successfully.
items:
$ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncErrorPresentation'
type: array
finishedAt:
description: Date and time the synchronization finished (ISO 8601, UTC). Null while the synchronization is still running.
example: '2026-06-09T14:31:12+00:00'
format: date-time
nullable: true
type: string
status:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncStatusPresentation'
description: 'Status of the synchronization: Running, Completed or CompletedWithErrors.'
example: CompletedWithErrors
syncId:
description: Identifier of the synchronization.
example: 1660e6c3-54fd-402f-be8e-7748efd94791
format: uuid
type: string
required:
- createdAt
- errors
- status
- syncId
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncStatusPresentation:
description: Status of a beneficiary synchronization.
enum:
- Running
- Completed
- CompletedWithErrors
type: string
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BeneficiarySyncItemDto:
additionalProperties: false
description: A single beneficiary to synchronize.
properties:
accountNumber:
description: Bank account number (IBAN/BBAN/Other).
example: FR1317515900006392295694K68
nullable: true
type: string
bankCountry:
description: Country of the bank where the account is located. Use ISO 3166 2-letters code.
example: FR
nullable: true
type: string
bankIdentifier:
description: Bank identifier code (BIC) of the bank where the account is located. Recommended for most payments.
example: SOGEFRPP
nullable: true
type: string
bankName:
description: Name of the bank the account is located. Use if required by your bank.
example: Société Générale
nullable: true
type: string
companyLegalId:
description: Legal registration identifier of the beneficiary company (e.g. SIRET, company number).
example: '552100554'
nullable: true
type: string
erpId:
description: 'Identifier of the beneficiary in your ERP. Used as the upsert key: an existing beneficiary with the same identifier is updated, otherwise a new one is created.'
example: BEN-10042
type: string
intermediaryBankIdentifier:
description: Bank identifier code (BIC) of the intermediary bank processing the payments. Use if required by your supplier/bank.
nullable: true
type: string
localClearingCode:
description: Local identifier of the bank. Usually useful when the account number is not an IBAN.
nullable: true
type: string
name:
description: Name of the beneficiary.
example: ACME Corporation
type: string
postalAddress:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BeneficiarySyncPostalAddressDto'
description: Postal address of the beneficiary.
nullable: true
supplierErpIds:
description: ERP identifiers of the suppliers to associate with this beneficiary.
items:
type: string
nullable: true
type: array
required:
- erpId
- name
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BankAccountPresentation:
additionalProperties: false
properties:
bankName:
nullable: true
type: string
bic:
nullable: true
type: string
country:
nullable: true
type: string
identifier:
nullable: true
type: string
intermediaryBankBic:
nullable: true
type: string
localClearingCode:
nullable: true
type: string
type: object
Microsoft.AspNetCore.Mvc.ProblemDetails:
additionalProperties: {}
properties:
detail:
nullable: true
type: string
instance:
nullable: true
type: string
status:
format: int32
nullable: true
type: integer
title:
nullable: true
type: string
type:
nullable: true
type: string
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.StartBeneficiarySyncDto:
additionalProperties: false
description: Payload of a beneficiary synchronization request.
properties:
items:
description: Beneficiaries to synchronize. Up to 15 000 items can be sent in a single request.
items:
$ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BeneficiarySyncItemDto'
type: array
required:
- items
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BeneficiarySyncPostalAddressDto:
additionalProperties: false
description: Postal address of a synchronized beneficiary.
properties:
city:
description: Name of the city.
example: Paris
nullable: true
type: string
country:
description: Country in which the beneficiary is located. Use ISO 3166 2-letters code.
example: FR
type: string
number:
description: Number of the building.
example: '42'
nullable: true
type: string
state:
description: State in which the beneficiary is located, if needed.
nullable: true
type: string
streetName:
description: Name of the street.
example: Av. des Champs-Élysées
nullable: true
type: string
zipCode:
description: ZIP code of the beneficiary location.
example: '75008'
nullable: true
type: string
required:
- country
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.EditBeneficiaryDto:
additionalProperties: false
description: Beneficiary's information to edit
properties:
bankAccount:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BankAccountDto'
description: Information about the bank account of the beneficiary
nullable: true
name:
description: Name of the beneficiary
example: John Doe
type: string
postalAddress:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Dtos.Beneficiaries.PostalAddressDto'
description: Information about the postal address of the beneficiary
nullable: true
required:
- name
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncErrorPresentation:
additionalProperties: false
description: A single item that failed during a beneficiary synchronization.
properties:
errorCode:
allOf:
- $ref: '#/components/schemas/PaymentsPreparation.Web.Models.Presentations.Beneficiary.BeneficiarySyncErrorCodePresentation'
description: Machine-readable error code identifying the reason the item failed.
example: InvalidIban
errorMessage:
description: Human-readable description of the error, when available.
nullable: true
type: string
rawData:
description: Raw JSON of the submitted item, echoed back to help you locate it.
type: string
rowIndex:
description: Zero-based index of the failing item in the submitted payload.
example: 0
format: int32
type: integer
required:
- errorCode
- rawData
- rowIndex
type: object
PaymentsPreparation.Web.Models.Dtos.Beneficiaries.BankAccountDto:
additionalProperties: false
description: Information about the bank account of the beneficiary
properties:
bankName:
description: Name of the bank the account is located. Use if required by your bank.
example: Société Général compte courant
nullable: true
type: string
bic:
description: Bank identifier code of the bank where the account is located. Recommended for most payments.
example: SOGEFRPP
nullable: true
type: string
country:
description: Country of the bank where the account is located. Use ISO 3166 2-letters code.
example: FR
nullable: true
type: string
identifier:
description: Bank account number (IBAN/BBAN/Other).
example: FR1317515900006392295694K68
nullable: true
type: string
intermediaryBankBic:
description: Bank identifier code of the intermediary bank processing the payments. Use if required by your supplier/bank.
nullable: true
type: string
localClearingCode:
description: Local identifier of the bank. Usually usefull when the account number is not an IBAN.
nullable: true
type: string
type: object
PaymentsPreparation.Web.Models.Presentations.Beneficiary.UncertaintyStatusPresentation:
enum:
- Uncertain
- NotUncertain
- Irrelevant
type: string
securitySchemes:
bearer:
bearerFormat: JWT
scheme: bearer
type: http
bearerAuth:
bearerFormat: OPAQUE
scheme: bearer
type: http