Request Business Key

The Qorpy API enables businesses to integrate with Nigeria's National Revenue Service (NRS) eInvoicing system. This documentation covers the business onboarding process, which is the first step in your integration journey.

POST {{baseURL}}/{{stage}}/external/request-business-key

Integration Workflow

Purpose

This endpoint registers your business with Qorpy's eInvoicing system and generates a unique Business Key that serves as your authentication credential for all subsequent API operations. You must complete this onboarding step before submitting e-Invoices.

Prerequisites

Before calling this endpoint, ensure you have:

✅ Registered your business with FIRS (Federal Inland Revenue Service)

✅ Selected Qucoon Limited as your preferred Access Point

✅ Obtained your business FIRS Entity ID and FIRS Business ID

Authentication

This endpoint does not require authentication. It is publicly accessible to allow new businesses to onboard. However, all fields are validated against FIRS records, and fraudulent requests will be rejected.

Request Specification

HTTP Headers

Header	Value	Required	Description
`Content-Type`	`application/json`	✅	Indicates JSON request body
`Accept`	`application/json` or `/`	✅	Specifies acceptable response format

Request Body Parameters

Parameter	Type	Required	Max Length	Validation	Description
`businessAddress`	string	✅	200	Non-empty	Complete business address including building number/name
`businessAddressLg`	string	✅	50	Must match valid LGA	Local Government Area (LGA) where business is located, refer to resources folder
`businessAddressStreetName`	string	✅	100	Non-empty	Street name of the business address
`businessCity`	string	✅	50	Non-empty	City/Town where business operates
`businessCountry`	string	✅	2	ISO 3166-1 alpha-2	Country code, refer to resources folder
`businessFirsId`	string	✅	36	UUID v4 format	FIRS-issued business ID
`businessPostalCode`	string	✅	10	6-digit numeric	Nigerian postal code (e.g., "101241")
`businessState`	string	✅	50	Must match valid state	Nigerian state where business is registered
`contactEmail`	string	✅	100	Valid email format	Primary contact email for API notifications and business key delivery
`entityFirsId`	string	✅	50	Alphanumeric + hyphens	FIRS-issued entity ID

Response Specification

Success Response (HTTP 200)

{
    "responseCode": "00",
    "responseMessage": "Business successfully registered for external API access.",
    "businessKey": "BK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-DEV-XXXXXXXXXXXX",
    "businessFirsId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX"
}

Response Fields

Field	Type	Description
`businessFirsId`	string	Echo of your business FIRS ID for confirmation
`businessKey`	string	Your unique API authentication key - Store this securely!
`responseCode`	string	Application-level status code (see codes below)
`responseMessage`	string	Human-readable description of the result

Response Codes

Code	Meaning	Action Required
`00`	Success	Business key generated successfully. Store the key securely.
`01`	Success	Business taxpayer ID not found in FIRS system.
`02`	Duplicate Request	Business already registered. Use existing business key.
`106`	FIRS Verification Failed	Provided FIRS credentials don't match FIRS records.

Important: The responseCode is separate from HTTP status codes. A 200 OK HTTP response can still contain error details in the responseCode field.

Error Responses

HTTP 400 - Bad Request

Cause: Invalid or missing required parameters

{
  "responseCode": "106",
  "responseMessage": "Validation failed: businessFirsId must be a valid format"
}

Common Validation Errors:

Invalid email format in contactEmail

Inaccurate businessFirsId

businessState not matching valid Nigerian states

businessPostalCode not a 6-digit number

businessCountry not "NG"

HTTP 401 - Unauthorized

Cause: FIRS credentials verification failed

{
    "responseCode": "04",
    "responseMessage": "Requested business ID not found under this taxpayer account",
    "businessKey": null,
    "businessFirsId": null
}

Resolution Steps:

Verify your businessFirsId matches your FIRS Tax Identification Number

Confirm your entityFirsId matches your CAC registration with FIRS

Contact FIRS if credentials are correct but still failing

Ensure your business registration is active and not suspended

HTTP 500 - Internal Server Error

Cause: Server-side processing error

{
  "responseCode": "99",
  "responseMessage": "An internal error occurred while processing your request",
  "requestId": "req_7h3k9m2p4s6v8x1z",
  "timestamp": "2026-02-12T10:30:45Z"
}

Resolution:

Retry the request after 2-3 minutes

If error persists after 3 attempts, contact support with the requestId

HTTP 503 - Service Unavailable

Cause: API maintenance or service unavailable

{
  "responseCode": "99",
  "responseMessage": "Service temporarily unavailable. Please try again later.",
  "retryAfter": 300,
  "timestamp": "2026-02-12T10:30:45Z"
}

Resolution:

Wait for the duration specified in retryAfter (in seconds)

Using Your Business Key

Once you receive your business key, use it for authentication in all subsequent API requests.

Security Best Practices:
✅ Store business key in environment variables or secure vault (e.g., AWS Secrets Manager, Azure Key Vault)
✅ Never commit business keys to version control

Test Credentials

Use your FIRS test values in the development environment:

Troubleshooting Guide

Issue: "FIRS verification failed"

Problem: Credentials don't match FIRS records
Checklist:

Is your business registration active with FIRS?

Have you selected Qucoon as your preferred Access Point on FIRS ?

Have you recently updated business details with FIRS? (Allow 48 hours for sync)

Is the entityFirsId accurate ?

Did you use the correct businessFirsId?

Compliance & Legal

Data Privacy

Your business information is:

Encrypted in transit (TLS 1.3) and at rest (AES-256)

Stored in Nigerian data centers compliant with NDPR (Nigeria Data Protection Regulation)

Shared only with FIRS for verification purposes

Terms of Use

By using this API, you agree to:

Provide accurate business information

Use business keys only for legitimate tax reporting

Not share or transfer business keys to unauthorized parties

Comply with all NRS eInvoicing regulations

Document Version: 1.2.0
Last Updated: February 12, 2026
API Version: v1

Request Business Key

Integration Workflow#

Purpose#

Prerequisites#

Authentication#

Request Specification#

HTTP Headers#

Request Body Parameters#

Response Specification#

Success Response (HTTP 200)#

Response Fields#

Response Codes#

Error Responses#

HTTP 400 - Bad Request#

HTTP 401 - Unauthorized#

HTTP 500 - Internal Server Error#

HTTP 503 - Service Unavailable#

Using Your Business Key#

Test Credentials#

Troubleshooting Guide#

Issue: "FIRS verification failed"#

Compliance & Legal#

Data Privacy#

Terms of Use#

Request

Responses