Version: 1.0.0

SMART Payroll API

REST API for SMART Payroll extension built on Microsoft Dynamics 365 Business Central. This API provides comprehensive functionality for managing employees, persons, labor contracts, positions, timesheets, payroll calculations, vacations, and other HR operations.

Authentication

This API supports two authentication methods:

1. Bearer Token (Recommended for Both SaaS and On-Premises)

Security Scheme: BearerAuth

How to use:

1. Obtain an OAuth 2.0 access token from Azure AD (see BearerAuth in Security Schemes for instructions)
2. Click the "Authorize" button at the top of this documentation
3. Paste your access token in the "Value" field
4. Click "Authorize" - all requests will now include the token automatically

Token Format: Azure AD JWT token obtained via OAuth 2.0 client credentials flow

Works for:

• ✅ Business Central SaaS (Cloud)
• ✅ Business Central On-Premises (with Azure AD authentication)

📖 See BearerAuth in Security Schemes below for detailed step-by-step instructions on obtaining the token.

API Conventions

• All endpoints follow OData v4 protocol standards
• Supports standard OData query options: $filter, $select, $expand, $orderby, $top, $skip
• Date fields use ISO 8601 format (YYYY-MM-DD)
• All timestamps include timezone information
• API responses include ETag headers for optimistic concurrency control

Quick Start

Step 1: Get Access Token

# Replace {tenant-id}, {client-id}, {client-secret} with your Azure AD credentials
curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={client-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=https://api.businesscentral.dynamics.com/.default"

Step 2: Use Token in API Calls

For SaaS:

curl -H "Authorization: Bearer {access_token}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant}/Production/api/smart/payroll/v1.0/companies({companyid})/persons"

For On-Premises:

curl -H "Authorization: Bearer {access_token}" \
  "https://bc-server:7048/BC230/api/smart/payroll/v1.0/companies({companyid})/persons"

Step 3: Use Swagger UI

For testing in this documentation:

1. Get your access token using the curl command above
2. Click "Authorize" button at the top
3. Paste the token value (without "Bearer" prefix)
4. Try any endpoint using "Try it out" button

Authentication

HTTP: Bearer Auth

Bearer Token Authentication (Recommended)

Provide the access token obtained from Azure AD OAuth 2.0. This method works for both Business Central SaaS and On-Premises deployments.

How to Get the Token

For Both SaaS and On-Premises:

Step 1: Get OAuth 2.0 Access Token

Request a token from Azure AD using client credentials flow:

curl -X POST "https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your-client-id}" \
  -d "client_secret={your-client-secret}" \
  -d "scope=https://api.businesscentral.dynamics.com/.default"

Step 2: Extract the access_token from response

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

Step 3: Use the token in this API documentation

1. Click the "Authorize" button at the top of this page
2. In the "Value" field, paste ONLY the access_token value (do NOT include "Bearer")
3. Click "Authorize" then "Close"
4. All API requests will now include: Authorization: Bearer {your_token}

Azure AD Application Setup

If you don't have an Azure AD application yet:

1. Register Application

• Go to Azure Portal → Azure Active Directory → App registrations
• Click "New registration"
• Name: "SMART Payroll API Client"
• Click "Register"

2. Add API Permissions

• Go to "API permissions" → "Add a permission"
• Select "Dynamics 365 Business Central"
• Choose "Application permissions"
• Select "Automation.ReadWrite.All"
• Click "Grant admin consent"

3. Create Client Secret

• Go to "Certificates & secrets"
• Click "New client secret"
• Copy the secret value immediately

4. Copy Your Credentials

• Tenant ID: From "Overview" page (Directory (tenant) ID)
• Client ID: From "Overview" page (Application (client) ID)
• Client Secret: From step 3

Important Notes

⏱️ Token Lifetime: Tokens expire in 1 hour. Request a new token when needed.
🔒 Security: Never expose your client_id/client_secret in client-side code.
✅ Reusability: Same token can be used for multiple API calls until expiration.
🌍 Works for both: Same process for SaaS and On-Premises (only API URL differs).

Quick PowerShell Example

# Get token
$body = @{
    grant_type    = "client_credentials"
    client_id     = "your-client-id"
    client_secret = "your-client-secret"
    scope         = "https://api.businesscentral.dynamics.com/.default"
}
$token = (Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token" -Body $body).access_token

# Use token
$headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Uri "https://api.businesscentral.dynamics.com/..." -Headers $headers

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT