Registration API Guide

This guide covers the Registration GET and POST endpoints in the core-api application.

Base URL

All registration endpoints are prefixed with:

/registrations/v1/registrations/

Endpoints Overview

Method	Endpoint	Description
GET	/registrations/v1/registrations/	List all registrations
POST	/registrations/v1/registrations/	Create a new registration
GET	/registrations/v1/registrations/{id}/	Get a specific registration
PUT	/registrations/v1/registrations/{id}/	Update a registration
PATCH	/registrations/v1/registrations/{id}/	Partially update a registration
DELETE	/registrations/v1/registrations/{id}/	Delete a registration

Authentication & Permissions

• Authentication: JWT token required in Authorization header
• Permissions:
  • View: REGISTRATION_VIEW
  • Create: REGISTRATION_CREATE
  • Edit: REGISTRATION_EDIT

GET /registrations/v1/registrations/

Description

Retrieve a list of registrations with optional filtering and pagination.

Query Parameters

Parameter	Type	Description
number	string	Filter by registration number (searches both number and number_local fields)
entity	UUID	Filter registrations by entity ID
taxable_jurisdiction	UUID	Filter registrations by taxable jurisdiction ID
entity_jurisdiction	UUID	Filter by entity jurisdiction ID
order_by	string	Order results by field. Options: entity_name, fiscal_code, number, date_of_filing_start, date_of_registration, date_registration_closed

Response Fields

Field	Type	Description
id	UUID	Unique identifier for the registration
entity_jurisdiction	UUID	Reference to the entity jurisdiction
taxable_jurisdiction_detail	Object	Full taxable jurisdiction details (read-only)
entity_detail	Object	Full entity details (read-only)
number	string	Registration number (max 20 chars)
number_local	string	Local registration number (max 20 chars)
fiscal_code	string	Fiscal code (max 16 chars)
date_of_registration	date	Date when registration became active
date_registration_closed	date	Date when registration was closed
date_of_filing_start	date	Date when filing obligations start
fiscal_representative_type	string	Type of fiscal representative
fiscal_representative_type_display	string	Human-readable fiscal representative type
registration_type	string	Type of registration (required)
registration_type_display	string	Human-readable registration type
status	string	Current status (computed field)
status_display	string	Human-readable status
direct_debit_setup	boolean	Whether direct debit is set up
entity_responsible_for_payment	string	Entity responsible for payments
entity_responsible_for_payment_display	string	Human-readable payment responsibility
iban	string	IBAN for payments (max 35 chars)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Example Request

GET /registrations/v1/registrations/?entity=123e4567-e89b-12d3-a456-426614174000&order_by=date_of_registration
Authorization: Bearer <jwt_token>

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_jurisdiction": "456e7890-e89b-12d3-a456-426614174000",
      "taxable_jurisdiction_detail": {
        "id": "789e0123-e89b-12d3-a456-426614174000",
        "name": "United Kingdom",
        "iso": "GB"
      },
      "entity_detail": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Example Company Ltd"
      },
      "number": "GB123456789",
      "number_local": "123456789",
      "fiscal_code": "FC123456",
      "date_of_registration": "2024-01-15",
      "date_registration_closed": null,
      "date_of_filing_start": "2024-02-01",
      "fiscal_representative_type": "not_required",
      "fiscal_representative_type_display": "Not Required",
      "registration_type": "standard",
      "registration_type_display": "Standard",
      "status": "active",
      "status_display": "Active",
      "direct_debit_setup": true,
      "entity_responsible_for_payment": "client_direct_debit",
      "entity_responsible_for_payment_display": "Client Direct Debit",
      "iban": "GB82WEST12345698765432",
      "created_at": "2024-01-10T10:30:00Z",
      "updated_at": "2024-01-15T14:20:00Z"
    }
  ]
}

POST /registrations/v1/registrations/

Description

Create a new registration for an entity in a specific taxable jurisdiction.

Request Fields

Field	Type	Required	Description
taxable_jurisdiction	string	Yes	ISO code of the taxable jurisdiction
entity	UUID	Yes	ID of the entity to register
number	string	No	Registration number (max 20 chars)
number_local	string	No	Local registration number (max 20 chars)
fiscal_code	string	No	Fiscal code (max 16 chars)
date_of_registration	date	No	Date when registration becomes active
date_registration_closed	date	No	Date when registration is closed
date_of_filing_start	date	No	Date when filing obligations start
fiscal_representative_type	string	No	Type of fiscal representative
registration_type	string	No	Type of registration (defaults to model default)
direct_debit_setup	boolean	No	Whether direct debit is set up
entity_responsible_for_payment	string	No	Entity responsible for payments
iban	string	No	IBAN for payments (max 35 chars)

Field Value Options

fiscal_representative_type

• agent - Agent
• not_required - Not Required
• managed_service_provider - Managed Service Provider

registration_type

• standard - Standard
• one_stop_shop - One Stop Shop
• import_one_stop_shop - Import One Stop Shop
• mini_one_stop_shop - Mini One Stop Shop
• sales_tax_registration - Sales Tax Registration
• digital_service_tax_registration - Digital Service Tax Registration
• lease_tax_registration - Lease Tax Registration
• suts_registration - SUTS Registration
• property_lease_tax_registration - Property Lease Tax Registration
• arsstc_registration - ARSSTC Registration

entity_responsible_for_payment

• client_direct_debit - Client Direct Debit
• client_manual_payment - Client Manual Payment
• managed_service_provider_direct_debit - Managed Service Provider Direct Debit

Validation Rules

1. Entity Permission: User must have REGISTRATION_CREATE permission for the specified entity
2. Jurisdiction-Registration Type: The combination of taxable_jurisdiction and registration_type must be configured in the system
3. Entity Jurisdiction: An EntityJurisdiction will be created automatically if it doesn't exist

Example Request

POST /registrations/v1/registrations/
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
  "taxable_jurisdiction": "GB",
  "entity": "123e4567-e89b-12d3-a456-426614174000",
  "registration_type": "standard",
  "fiscal_representative_type": "not_required",
  "date_of_registration": "2024-01-15",
  "date_of_filing_start": "2024-02-01",
  "direct_debit_setup": true,
  "entity_responsible_for_payment": "client_direct_debit",
  "iban": "GB82WEST12345698765432"
}

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_jurisdiction": "456e7890-e89b-12d3-a456-426614174000",
  "taxable_jurisdiction_detail": {
    "id": "789e0123-e89b-12d3-a456-426614174000",
    "name": "United Kingdom",
    "iso": "GB"
  },
  "entity_detail": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Example Company Ltd"
  },
  "number": "",
  "number_local": "",
  "fiscal_code": "",
  "date_of_registration": "2024-01-15",
  "date_registration_closed": null,
  "date_of_filing_start": "2024-02-01",
  "fiscal_representative_type": "not_required",
  "fiscal_representative_type_display": "Not Required",
  "registration_type": "standard",
  "registration_type_display": "Standard",
  "status": "pending",
  "status_display": "Pending",
  "direct_debit_setup": true,
  "entity_responsible_for_payment": "client_direct_debit",
  "entity_responsible_for_payment_display": "Client Direct Debit",
  "iban": "GB82WEST12345698765432",
  "created_at": "2024-01-10T10:30:00Z",
  "updated_at": "2024-01-10T10:30:00Z"
}

Status Calculation

The status field is computed based on dates:

• PENDING: No date_of_registration or date_of_registration is in the future
• ACTIVE: date_of_registration is today or in the past, and no date_registration_closed or date_registration_closed is in the future
• INACTIVE: date_registration_closed is today or in the past

Error Responses

400 Bad Request

{
  "detail": "There is no taxable jurisdiction - registration type combination configured."
}

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

404 Not Found

{
  "detail": "Not found."
}

Caching

• GET requests are cached for 5 minutes
• Cache varies on Authorization header to ensure user-specific data

Notes

• All UUIDs are version 4 UUIDs
• Dates are in ISO 8601 format (YYYY-MM-DD)
• Timestamps are in ISO 8601 format with timezone (YYYY-MM-DDTHH:MM:SSZ)
• The API uses Django REST Framework pagination for list endpoints
• Entity jurisdictions are created automatically when creating registrations
• Updates to date_registration_closed trigger deregistration services