First Steps

Set up your credentials

In the Developer Platform, open your app and locate the App Overview panel on the right-hand side.

You will find the following credentials:

• App ID
• App Secret

These are required to authenticate your app against the DevAPI.

⚠️

Security notice

Never expose your App Secret in frontend code or public repositories.

Generate a new App Secret

If needed, you can rotate your secret at any time:

1. Go to App Overview
2. Click Generate new secret key
3. Update your application configuration

Once regenerated, the previous secret becomes invalid immediately.

App Status

Each app in the Developer Platform has a lifecycle status that defines its editability, visibility, and usage permissions.

stateDiagram-v2
    [*] --> DRAFT

    DRAFT --> PENDING: Submit for approval
    PENDING --> APPROVED: Review approved
    PENDING --> DECLINED: Review declined

    DECLINED --> DRAFT: Fix issues & resubmit

    APPROVED --> PUBLISHED: Publish app
    APPROVED --> BLOCKED: Policy / security issue

    PUBLISHED --> BLOCKED: Policy / security issue

Draft (recommended)

While the app status is Draft:

• Scopes can be modified at any time
• The app is fully functional
• The app can be authorised in only one account
• You can make requests to the DevAPI

We recommend keeping your app in Draft during development and testing.

Approved

When your app is ready for production click Submit for approval (top-right corner)

The app is submitted for technical review. The status is updated automatically once the review is completed.

⚠️

Important limitation

Once an app is approved, its scopes are locked and can no longer be modified by the developer. To request scope changes for an approved app, please contact your Account Manager.

Make sure all required scopes are configured before submitting the app for approval.

Required setup before calling the DevAPI

Before making API requests, make sure that:

• The app is configured with the required Scopes
• The target account is listed under Authorised Accounts
• The app is Installed for the target Company / Enterprise

Once these steps are completed, you can start calling the DevAPI.

Authentication

Authentication is token-based. Use your App ID and App Secret to request an Access Token, then include it in the Authorization header for API requests. Access tokens expire and can be renewed using a Refresh Token.

sequenceDiagram
  autonumber
  participant Client as Integration (Backend)
  participant Auth as DevAPI Auth
  participant API as DevAPI

  Client->>Auth: POST /v1/auth/token (appid, appsecret)
  Auth-->>Client: { accessToken, refreshToken, expires }

  Client->>API: GET /v1/... (Authorization: accessToken)
  API-->>Client: 200 OK (data)

Request an access token

Use your App ID and App Secret to obtain an access token.

Example

curl -X POST https://api.timify.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "YOUR_APP_ID",
    "appsecret": "YOUR_APP_SECRET"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "def50200a1b2c3d4...",
  "expires": 7200
}

Make your first API call

Once you have obtained a valid Access Token, you can start calling the DevAPI.

All API requests must include the access token in the Authorization header.

Example

The following example retrieves company details.

curl -X GET "https://api.timify.com/v1/companies?company_id=YOUR_COMPANY_ID" \
  -H "Authorization: YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "63fa22b81d77389d476518bc",
      "metadata": {
        "test_key": "dummy_value",
        "test-key": 5,
        "testKey": false,
        "test_key_integer": 3.14
      },
      "name": "Berlin Office",
      "tradingName": "Berlin Tech Solutions",
      "contactEmail": "[email protected]",
      "description": "Main office in Berlin",
      "externalId": "BER_001",
      "slug": "berlin-tech",
      "plan": "ENTERPRISE",
      "currency": "EUR",
      "region": "EUROPE",
      "phone": {
        "country": "DE",
        "phone": "+493012345678",
        "prefix": "49",
        "number": "3012345678"
      },
      "onlineStatus": {
        "isOnline": true
      },
      "address": {
        "placeId": "ChIJAVkDPzdOqEcRcDteW0YgIQQ",
        "latitude": 52.520008,
        "longitude": 13.404954,
        "street": "Unter den Linden",
        "streetNumber": "77",
        "city": "Berlin",
        "country": "de",
        "zipCode": "10117",
        "formatted": "Unter den Linden 77, 10117 Berlin, Germany",
        "details": null
      },
      "billingData": null,
      "timezone": "Europe/Berlin",
      "locale": "de-DE",
      "coverUrl": "https://data-stg.timify.com/images/default-cover.jpg",
      "ownerEmail": "[email protected]",
      "businessSectors": ["Technology", "Consulting"],
      "settings": {
        "servicesAllocation": null
      },
      "enterprise": {
        "id": "60bfe497c94358349c2ee7e0",
        "name": "Tech Solutions Group",
        "slug": "tech-solutions",
        "settings": {
          "hasBookerServicesSignature": true,
          "isCompanyTagsLocalUpdateForbidden": false,
          "isServiceLocalUpdateForbidden": null,
          "isCourseLocalUpdateForbidden": null,
          "isCustomersLocalUpdateForbidden": false,
          "isResourceLocalUpdateForbidden": false,
          "isSettingsLocalUpdateForbidden": false,
          "allowOnlyGlobalCustomers": false,
          "callCentreEnabled": true
        }
      }
    }
  ]
}

Troubleshooting & FAQs

App not visible in Branch Manager?

• Confirm the correct Enterprise account is listed under Authorised Accounts
• Ensure the app is installed for that Enterprise

No data returned by the API?

Check that:

• The app is installed
• Required scopes are enabled
• The authenticated account has access to the requested resources

Need help?

For any DevAPI-related questions, please contact your Account Manager, who will coordinate with the relevant technical teams.