Getting Started

Beacon API Documentation

Copied!

Beacon API Complete DocumentationCopied!

Table of ContentsCopied!

Introduction
Authentication
Base URLs
API Endpoints
Common Data Structures
Error Handling
Pagination
Best Practices
Examples
Changelog
Support

1. IntroductionCopied!

The Beacon API provides a comprehensive set of endpoints for various financial and banking operations. This API allows developers to integrate bill payments, international deposits, notifications, OTP services, and vault management into their applications.

2. AuthenticationCopied!

The Beacon API uses bearer token authentication. Include the token in the Authorization header of your requests:

Authorization: Bearer YOUR_API_KEY

3. Base URLsCopied!

The API has different base URLs for different environments:

Production: https://api.beaconbank.ca/v1
Development: https://dev.api.beaconbank.ca
Staging: https://stage.api.beaconbank.ca

4. API EndpointsCopied!

4.1 Bill Payment Services

Create a Bill Payment

POST /bills

Request Body:

{
  "amountInCents": "string",
  "billPaymentId": "string"
}

Response: Bill object

Get Bill Payments

GET /bills
Query Parameters:
- pageSize (integer, default: 10)
- pageNumber (integer, default: 0)
Response: Paginated list of bill payments

Get Bill Payment Details

GET /bills/{billId}
Response: Bill object

Cancel Bill Payment

POST /bills/{billId}/cancel
Response: Bill payment cancel response

Get Bill Providers

GET /bill-providers
Query Parameters:
- type (string, enum: ["popular", "regular"], default: "popular")
Response: List of bill providers

Validate Biller

POST /bill-providers/{billerCode}/validate
Request Body:
```
{
  "accountNumber": "string"
}
```
Response: Validation result

4.2 International Deposit Services

Retrieve SWIFT Details

GET /international-deposit/swift-details
Response: SWIFT details object

Generate SWIFT Details

POST /international-deposit/swift-details
Response: Generated SWIFT details object

4.3 Notification Services

Update Notification Preferences

PATCH /notification-preferences
Request Body: Notification preferences object
Response: Updated notification preferences

Get Notification Preferences

GET /notification-preferences
Response: Notification preferences object

Set Push Token

POST /push-token

Request Body:

{
  "deviceId": "string",
  "token": "string",
  "tokenProvider": "string"
}

Response: Success message

Delete Push Token

DELETE /push-token
Request Body:
```
{
  "deviceId": "string"
}
```
Response: Success message

4.4 OTP Services

Request OTP

POST /otp/request

Request Body:

{
  "phoneNumber": "string",
  "countryCode": "string"
}

Response: OTP request status message

Validate OTP

POST /otp/validate

Request Body:

{
  "phoneNumber": "string",
  "otp": "string"
}

Response: OTP validation result

4.5 Core Beacon Services

Create Transfer

POST /transfers
Request Body: Transfer request object
Response: Transfer object

Get Transfers

GET /transfers
Query Parameters:
- transferType (string)
- pageSize (integer)
- pageNumber (integer)
- contactId (string)
Response: Paginated list of transfers

Get Contacts

GET /contacts
Query Parameters:
- transferType (string)
- recent (boolean)
- pageSize (integer)
- pageNumber (integer)
Response: Paginated list of contacts

Create Contact

POST /contacts
Request Body: Contact creation request
Response: Created contact object

Get Planning Lists

GET /planning_lists
Query Parameters:
- num_tasks (integer)
- archive (boolean)
- order_tasks_by (string)
- pageNumber (integer)
- pageSize (integer)
Response: Paginated list of planning lists

Create Planning List

POST /planning_lists
Request Body: Planning list input object
Response: Created planning list object

Get Templates

GET /templates
Query Parameters:
- tmpl_type (string)
- popular (boolean)
- recommended (boolean)
- num_tasks (integer)
- pageNumber (integer)
- pageSize (integer)
Response: List of templates

Generate Pre-signed URL for Profile Picture

GET /users/me/profile_picture/presigned_url
Response: Pre-signed URL object

Get Blogs

GET /blogs
Response: List of blog posts

Create Bookmark

POST /bookmarks
Request Body: Bookmark object
Response: Created bookmark object

Get Questionnaire

GET /questionnaire
Response: Questionnaire object

Submit Answers

POST /answers
Request Body: Answer object
Response: Submitted answer object

Get Recommended Templates

POST /recommendations/templates
Response: List of recommended templates

Get Verification Workflows

GET /verifications
Query Parameters:
- status (string)
Response: List of verification workflows

Get Security Questions

GET /security-questions
Query Parameters:
- count (integer, default: 5)
Response: List of security questions

4.6 Vault Services

Create Vault Account

POST /vault-accounts
Response: Created vault account object

Get Vault Accounts

GET /vault-accounts
Response: List of vault accounts

Get Account Transactions

GET /transactions
Query Parameters:
- pageNumber (integer)
- pageSize (integer)
- dateFrom (string, date)
- dateTo (string, date)
Response: Paginated list of transactions

Create Card

POST /cards
Request Body: Card creation request
Response: Created card object

Get Cards

GET /cards
Query Parameters:
- status (array of strings)
- nextPageToken (string)
- pageSize (integer)
Response: Paginated list of cards

Get Disclosures

GET /disclosures
Query Parameters:
- signed (boolean)
Response: List of disclosures

Create Address

POST /addresses
Request Body: Address object
Response: Created address object

Get External Accounts

GET /external-accounts
Query Parameters:
- nextPageToken (string)
- pageSize (integer)
Response: Paginated list of external accounts

5. Common Data StructuresCopied!

Bill Object

{
  "id": "string",
  "billAccountNumber": "string",
  "customerName": "string",
  "billerCode": "string",
  "billerName": "string",
  "amountInCents": "string",
  "currency": "string",
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Contact Object

{
  "id": "string",
  "name": "string",
  "interac": {
    "emailAddress": "string"
  },
  "createdAt": "string",
  "updatedAt": "string"
}

Transfer Object

{
  "id": "string",
  "contactId": "string",
  "contact": {
    "$ref": "#/components/schemas/contact"
  },
  "type": "string",
  "amountInCents": "string",
  "status": "string",
  "transferDetails": {
    "oneOf": [
      {
        "$ref": "#/components/schemas/interacTransfer"
      }
    ]
  },
  "createdAt": "string",
  "updatedAt": "string",
  "canceledAt": "string"
}

Card Object

{
  "cardStatus": "string",
  "memo": "string",
  "statusReason": "string",
  "accountId": "string",
  "cardProductId": "string",
  "creationTime": "string",
  "userId": "string",
  "id": "string",
  "form": "string",
  "embossedName": {
    "line1": "string",
    "line2": "string"
  },
  "expirationMonth": 0,
  "expirationYear": 0,
  "expirationTime": "string",
  "isPinSet": true,
  "lastFour": "string",
  "lastModifiedTime": "string",
  "reissueReason": "string",
  "reissuedFromId": "string",
  "reissuedToId": "string",
  "timestampPinSet": "string",
  "cardType": "string",
  "bin": "string",
  "cardBrand": "string",
  "fulfillmentDetails": {
    "$ref": "#/components/schemas/fulfillmentDetails"
  },
  "shippingAddress": {
    "$ref": "#/components/schemas/address"
  }
}

6. Error HandlingCopied!

The API uses standard HTTP status codes. In case of an error, the response will include an error object:

{
  "code": "ERROR_CODE",
  "title": "Error Title",
  "type": "error_type",
  "message": "Detailed error message"
}

Common error codes:

400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: Internal Server Error

7. PaginationCopied!

Many list endpoints support pagination using

pageSize

and

pageNumber

query parameters:

GET /endpoint?pageSize=10&pageNumber=2

The response will include pagination metadata:

{
  "count": 50,
  "pageNumber": 2,
  "pageSize": 10,
  "totalPages": 5
}

Some endpoints use token-based pagination with

nextPageToken

parameter.

8. Best PracticesCopied!

Always use HTTPS for API calls.
Keep your API keys secure and don't expose them in client-side code.
Implement proper error handling in your applications.
Use pagination for large data sets to improve performance.
Cache responses when appropriate to reduce API calls.
Validate user input before sending it to the API.
Implement retry logic with exponential backoff for failed requests.
Monitor your API usage and set up alerts for unusual activity.

9. ExamplesCopied!

Creating a Bill Payment

Request:

POST /bills HTTP/1.1
Host: api.beaconbank.ca
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "amountInCents": "5000",
  "billPaymentId": "some_puid"
}

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING",
  "amountInCents": "5000",
  "billerCode": "123456",
  "billerName": "Rogers",
  "billAccountNumber": "ACC123456",
  "customerName": "John Doe",
  "currency": "CAD",
  "createdAt": "2024-10-18T10:00:00Z",
  "updatedAt": "2024-10-18T10:00:00Z"
}

Retrieving Transactions

Request:

GET /transactions?pageSize=5&pageNumber=1 HTTP/1.1
Host: api.beaconbank.ca
Authorization: Bearer YOUR_API_KEY

Response:

{
  "transactions": [
    {
      "txnDate": "2024-10-18",
      "metadata": {
        "spent": 250.5
      },
      "data": [
        {
          "id": "trn_fba5b240-0e68-4e64-aca6-f12022dc4be3",
          "description": "Grocery Store Purchase",
          "amount": 75.50,
          "currency": "CAD",
          "status": "COMPLETED",
          "date": "2024-10-18",
          "type": "CARD",
          "createdAt": "2024-10-18T15:30:00Z",
          "updatedAt": "2024-10-18T15:30:00Z"
        },
        {
          "id": "trn_abc1234-5678-90de-fgh1-23456789ijkl",
          "description": "Online Shopping",
          "amount": 175.00,
          "currency": "CAD",
          "status": "COMPLETED",
          "date": "2024-10-18",
          "type": "CARD",
          "createdAt": "2024-10-18T18:45:00Z",
          "updatedAt": "2024-10-18T18:45:00Z"
        }
      ]
    }
  ],
  "count": 50,
  "pageNumber": 1,
  "pageSize": 5,
  "totalPages": 10
}

10. ChangelogCopied!

The API documentation doesn't include a changelog. For the most up-to-date information on API changes, contact Beacon support.

11. SupportCopied!

For additional support or questions about the Beacon API, contact the support team at support@beaconbank.ca.

Remember to always refer to the official documentation for the most accurate and up-to-date information about the Beacon API.