Onboarding API: how it works¶

With the Onboarding API you activate new clients (VAT numbers, ΑΦΜ) on your API key, with no emails and no paperwork. You send the client's details, the client signs the contract, Novus approves, and the system completes the activation and the Provider declaration to AADE (the Greek tax authority) on its own.

sequenceDiagram
    autonumber
    participant SH as You (software house)
    participant NP as Novus Onboarding API
    participant CL as Client
    participant NV as Novus (review)
    participant AADE as AADE
    SH->>NP: POST /api/v1/requests (client details)
    NP-->>SH: requestId, status PENDING_SIGNATURE
    NP-)CL: Email with the contract (PDF) and an upload link
    CL->>NP: Uploads the signed contract (or you do: POST …/signed-contract)
    NP-->>SH: status UNDER_REVIEW (webhook)
    NV->>NP: Approval (or ACTION_REQUIRED with a reason)
    NP->>NP: Activates the VAT number on your API key, archives the contract
    NP->>AADE: Provider declaration
    NP-->>SH: status APPROVED, provisioning COMPLETED (webhook)
    NP-)CL: Email: "accept the declaration in myAADE within 10 days"

Request statuses¶

Status	Meaning	What you do
`PENDING_SIGNATURE`	The contract was generated and sent to the client.	Wait for the signature, or upload it yourself.
`UNDER_REVIEW`	A signed contract exists and Novus is reviewing it.	Nothing. This usually takes 1 business day.
`ACTION_REQUIRED`	The contract was not accepted (e.g. it is not legible). The reason is in `message`.	Upload a new signed contract.
`APPROVED`	Approved. The technical completion is shown in `provisioning`.	When `provisioning.status = COMPLETED`, you issue documents for this VAT number as normal.
`REJECTED`	Rejected. Final status.	See `message`.
`CANCELLED`	Cancelled by you or by Novus. Final status.	If needed, create a new request.

stateDiagram-v2
    [*] --> PENDING_SIGNATURE: NEW_CONTRACT
    [*] --> UNDER_REVIEW: LINK_EXISTING
    PENDING_SIGNATURE --> UNDER_REVIEW: signed contract
    UNDER_REVIEW --> ACTION_REQUIRED: Novus asks for a correction
    ACTION_REQUIRED --> UNDER_REVIEW: new contract
    UNDER_REVIEW --> APPROVED
    UNDER_REVIEW --> REJECTED
    PENDING_SIGNATURE --> CANCELLED
    ACTION_REQUIRED --> CANCELLED
    UNDER_REVIEW --> CANCELLED

Two request types: the system decides¶

`requestType`	When	Contract?
`NEW_CONTRACT`	The VAT number has no contract with Novus.	Yes. The client signs it.
`LINK_EXISTING`	The VAT number already has a contract, e.g. through another software house.	No. Only the link to your API key is created, after approval.

The contract and the Provider declaration happen once per client, no matter how many software houses serve that client.

The contract¶

It is generated automatically from the request details and is already signed by Novus.
It is sent to the client's contactInfo.email together with an upload link. The email is always sent, because the contract is between Novus and the client.
Any legible signature is accepted: scanned handwritten, via gov.gr, or digital. It must include all pages, upright and clean. PDF only, up to 15 MB.
If the client makes B2C sales, the request must also include the client's internet service provider (ispDetails). AADE requires this.

After approval¶

The VAT number is activated on your API key and you can start issuing.
Novus sends the Provider declaration to AADE. The client must accept it in myAADE within 10 days. Otherwise it is deemed tacitly accepted (A.1112/2025).
Ending the cooperation after approval is possible only through Novus.

In the sandbox¶

In the sandbox, no Provider declaration is submitted to AADE and no real contract is created. Emails, however, are sent as normal (e.g. the contract to contactInfo.email), so use only your own test addresses. You can also test with real VAT numbers. To move a test request to APPROVED, send us its requestId.

Next steps¶

All calls: Endpoints
Real-time notifications: Webhooks
For your application: OpenAPI (YAML) · Postman. In Postman, set apiKey in the collection Variables and run the folder "1. Ροή onboarding" (onboarding flow) in order.