platform

Platform

Manage the building blocks of Codat, including companies, connections, and more.

Summary

Platform API: Platform API

An API for the common components of all of Codat's products.

These end points cover creating and managing your companies, data connections, and integrations.

Read about the building blocks of Codat... | See our OpenAPI spec

Endpoints

Endpoints	Description
Companies	Create and manage your SMB users' companies.
Connections	Create new and manage existing data connections for a company.
Connection management	Configure connection management UI and retrieve access tokens for authentication.
Webhooks	Create and manage webhooks that listen to Codat's events.
Integrations	Get a list of integrations supported by Codat and their logos.
Refresh data	Initiate data refreshes, view pull status and history.
Settings	Manage company profile configuration, sync settings, and API keys.
Push data	Initiate and monitor Create, Update, and Delete operations.
Supplemental data	Configure and pull additional data you can include in Codat's standard data types.
Custom data type	Configure and pull additional data types that are not included in Codat's standardized data model.

SDK Installation

Getting started

JDK 11 or later is required.

The samples below show how a published SDK artifact is used:

Gradle:

implementation 'io.codat:platform:2.0.0'

Maven:

<dependency>
    <groupId>io.codat</groupId>
    <artifactId>platform</artifactId>
    <version>2.0.0</version>
</dependency>

How to build

After cloning the git repository to your file system you can build the SDK artifact from source to the build directory by running ./gradlew build on *nix systems or gradlew.bat on Windows systems.

If you wish to build from source and publish the SDK artifact to your local Maven repository (on your filesystem) then use the following command (after cloning the git repo locally):

On *nix:

./gradlew publishToMavenLocal -Pskip.signing

On Windows:

gradlew.bat publishToMavenLocal -Pskip.signing

Example Usage

SDK Example Usage

Example

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

Available Resources and Operations

Available methods

companies()

addProduct - Add product
create - Create company
delete - Delete a company
get - Get company
getAccessToken - Get company access token
list - List companies
removeProduct - Remove product
update - Update company

connectionManagement()

getAccessToken - Get access token

connectionManagement().corsSettings()

get - Get CORS settings
set - Set CORS settings

connections()

create - Create connection
delete - Delete connection
get - Get connection
list - List connections
unlink - Unlink connection
updateAuthorization - Update authorization

customDataType()

configure - Configure custom data type
getConfiguration - Get custom data configuration
list - List custom data type records
refresh - Refresh custom data type

integrations()

get - Get integration
getBranding - Get branding
list - List integrations

pushData()

getModelOptions - Get push options
getOperation - Get push operation
listOperations - List push operations

refreshData()

all - Refresh all data
byDataType - Refresh data type
get - Get data status
getPullOperation - Get pull operation
listPullOperations - List pull operations

settings()

createApiKey - Create API key
deleteApiKey - Delete API key
getProfile - Get profile
getSyncSettings - Get sync settings
listApiKeys - List API keys
updateProfile - Update profile
updateSyncSettings - Update all sync settings

supplementalData()

configure - Configure
getConfiguration - Get configuration

webhooks()

~~create~~ - Create webhook (legacy) ⚠️ Deprecated
createConsumer - Create webhook consumer
deleteConsumer - Delete webhook consumer
~~get~~ - Get webhook (legacy) ⚠️ Deprecated
~~list~~ - List webhooks (legacy) ⚠️ Deprecated
listConsumers - List webhook consumers

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an exception.

By default, an API error will throw a models/errors/SDKError exception. When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the createApiKey method throws the following exceptions:

Error Type	Status Code	Content Type
models/errors/ErrorMessage	400, 401, 402, 403, 409, 429, 500, 503	application/json
models/errors/SDKError	4XX, 5XX	/

Example

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

Server Selection

Override Server URL Per-Client

The default server can also be overridden globally using the .serverURL(String serverUrl) builder method when initializing the SDK client instance. For example:

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .serverURL("https://api.codat.io")
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme
`authHeader`	apiKey	API key

You can set the security parameters through the security builder method when initializing the SDK client instance. For example:

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, you can provide a RetryConfig object through the retryConfig builder method:

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import io.codat.platform.utils.BackoffStrategy;
import io.codat.platform.utils.RetryConfig;
import java.lang.Exception;
import java.util.concurrent.TimeUnit;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .retryConfig(RetryConfig.builder()
                    .backoff(BackoffStrategy.builder()
                        .initialInterval(1L, TimeUnit.MILLISECONDS)
                        .maxInterval(50L, TimeUnit.MILLISECONDS)
                        .maxElapsedTime(1000L, TimeUnit.MILLISECONDS)
                        .baseFactor(1.1)
                        .jitterFactor(0.15)
                        .retryConnectError(false)
                        .build())
                    .build())
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

If you'd like to override the default retry strategy for all operations that support retries, you can provide a configuration at SDK initialization:

package hello.world;

import io.codat.platform.CodatPlatform;
import io.codat.platform.models.errors.ErrorMessage;
import io.codat.platform.models.operations.CreateApiKeyResponse;
import io.codat.platform.models.shared.CreateApiKey;
import io.codat.platform.models.shared.Security;
import io.codat.platform.utils.BackoffStrategy;
import io.codat.platform.utils.RetryConfig;
import java.lang.Exception;
import java.util.concurrent.TimeUnit;

public class Application {

    public static void main(String[] args) throws ErrorMessage, Exception {

        CodatPlatform sdk = CodatPlatform.builder()
                .retryConfig(RetryConfig.builder()
                    .backoff(BackoffStrategy.builder()
                        .initialInterval(1L, TimeUnit.MILLISECONDS)
                        .maxInterval(50L, TimeUnit.MILLISECONDS)
                        .maxElapsedTime(1000L, TimeUnit.MILLISECONDS)
                        .baseFactor(1.1)
                        .jitterFactor(0.15)
                        .retryConnectError(false)
                        .build())
                    .build())
                .security(Security.builder()
                    .authHeader("Basic BASE_64_ENCODED(API_KEY)")
                    .build())
            .build();

        CreateApiKey req = CreateApiKey.builder()
                .name("azure-invoice-finance-processor")
                .build();

        CreateApiKeyResponse res = sdk.settings().createApiKey()
                .request(req)
                .call();

        if (res.apiKeyDetails().isPresent()) {
            // handle response
        }
    }
}

Support

If you encounter any challenges while utilizing our SDKs, please don't hesitate to reach out for assistance. You can raise any issues by contacting your dedicated Codat representative or reaching out to our support team. We're here to help ensure a smooth experience for you.

Name	Name	Last commit message	Last commit date
parent directory ..
.speakeasy	.speakeasy
docs	docs
gradle/wrapper	gradle/wrapper
src/main/java/io/codat/platform	src/main/java/io/codat/platform
.gitattributes	.gitattributes
.gitignore	.gitignore
CONTRIBUTING.md	CONTRIBUTING.md
README.md	README.md
RELEASES.md	RELEASES.md
USAGE.md	USAGE.md
build-extras.gradle	build-extras.gradle
build.gradle	build.gradle
gradlew	gradlew
gradlew.bat	gradlew.bat
settings.gradle	settings.gradle

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expand file tree

README.md

Platform

Summary

Endpoints

Table of Contents

SDK Installation

Getting started

How to build

Example Usage

SDK Example Usage

Example

Available Resources and Operations

companies()

connectionManagement()

connectionManagement().corsSettings()

connections()

customDataType()

integrations()

pushData()

refreshData()

settings()

supplementalData()

webhooks()

Error Handling

Example

Server Selection

Override Server URL Per-Client

Authentication

Per-Client Security Schemes

Retries

Support

Library generated by Speakeasy

Search code, repositories, users, issues, pull requests...

FilesExpand file tree

platform

Directory actions

More options

Directory actions

More options

Latest commit

History

platform

Folders and files

parent directory

Platform

Summary

Endpoints

Table of Contents

SDK Installation

Getting started

How to build

Example Usage

SDK Example Usage

Example

Available Resources and Operations

Error Handling

Example

Server Selection

Override Server URL Per-Client

Authentication

Per-Client Security Schemes

Retries

Support

Library generated by Speakeasy

Expand file tree