Welcome to the Getting Started Guide for our Public API! This guide will walk you through the basic steps needed to begin using the API, from signing up to making your first authenticated request.

Step 1: Obtain Your API Key

To use the Public API, you'll first need to sign up for an account:

Log in to access your organization (Please create an account if you don’t already have one).
Navigate to the Settings > API Keys .
1. Note: Only users with Admin role can create keys.
Click on Generate a new API Key.
Name your API Key and click Generate.
Copy your API Key, this is the last time it is visible.
Make a note of your Organization ID, you will need this to make any request.

Your API key is your unique identifier, so make sure to store it securely. It will be required for every API request you make.

❗️
Never expose your API key to unauthorized individuals or publicly!
Your API key grants access to your account and its resources. Never expose your API key to unauthorized individuals or publicly. Treat it like a password and store it securely.
If you believe your key has been compromised, delete it from the Settings > API Keyspage.

Step 2: Making a request

First Request

Let's begin by testing the new API Key with a request!

The endpoint we will use is GET https://api.itmc.i.moneyforward.com/api/v1/organizations/{id} (API Reference). This endpoint returns information about the organization the API Key belongs to.

Most endpoints require an Organization ID in the request path. If you don't have yours, you can find it on the Settings > API Keys page.

Notice that the endpoint path has id wrapped in curly braces ({id}). Most request paths include dynamic fields, and placeholders like {placeholder} are used to represent them. When making a request, replace the placeholder with the appropriate value, such as the organization ID, service ID, or user ID.

🚧
Non-alphanumeric values should be encoded
The variable part of the URL must be properly encoded (if it contains non-alphanumeric characters) to ensure it is safe for URLs. Encoding methods vary depending on the language. In JavaScript, use encodeURIComponent; in Python, use urllib.parse.quote; in Go, use url.PathEscape. Please refer to the documentation for your specific language or framework.

You'll need to authenticate your requests by including your API key in the Authorization header of every request. For more detailed information, please refer to the Authentication page.

Now, let's put everything together and make our first request:

// We use Axios in our example, but feel free to choose your favorite library
//
// npm install axios --save
import axios from "axios"; // ESM
// const axios = require("axios"); // CJS

main();
async function main() {
  const orgId = encodeURIComponent("<YOUR ORG ID>"); // not required for numbers, but good practice
  const token = "<YOUR API KEY>";
  const options = {
    method: "GET",
    url: `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}`,
    headers: {
      accept: "application/json",
      authorization: `Bearer ${token}`,
    },
  };

  const response = await axios.request(options);
  console.log(response.data);
}

If everything was done correctly, you should receive a response similar to this:

{
  id: 1,
  name: 'Example',
  uniqueName: 'example',
  status: 'active',
  systemLanguage: 'en',
  domains: [ 'example.com' ],
  location: 'jp',
  forwardingEmail: 'example-abcdefg@forwarding.i.moneyforward.com',
  recipientEmail: null,
  timeZone: 'Asia/Tokyo',
  trialCount: 1
}

Aaand that's it!

More Examples

Pagination and Filtering

Let's try another endpoint, this time using pagination and some filtering. We'll use GET https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/services (API Reference), which returns all the services integrated with the organization, along with some additional details, such as a list of workspaces belonging to each service.

In this example, we'll sort by serviceName in descending order and limit the response to one result per request. For more detailed information, please refer to the Pagination page.

Let's check out the code!

// We use Axios in our example, but feel free to choose your favorite library
//
// npm install axios --save
import axios from "axios"; // ESM
// const axios = require("axios"); // CJS

main();
async function main() {
  const orgId = encodeURIComponent("<YOUR ORG ID>"); // not required for numbers, but good practice
  const token = "<YOUR API KEY>";
  const options = {
    method: "GET",
    url: `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/services`,
    headers: {
      accept: "application/json",
      authorization: `Bearer ${token}`,
    },
    // parameters will be automatically encoded and included in the URL as query parameters
    params: {
      // Please see https://admina-docs.readme.io/reference/publicgetorganizationservices
      // It describes all fields and their role in the request
      limit: 1,
      sortBy: "serviceName",
      sortOrder: "DESC",
      cursor: undefined, // undefined is skipped during serialization
    },
  };

  do {
    console.log("> Fetching services...");
    const response = await axios.request(options);
    console.log("Total services: ", response.data.items.length);
    console.log("Service names: ", response.data.items.map((item) => item.name));
    console.log("Next cursor: ", response.data.meta.nextCursor);

    options.params.cursor = response.data.meta.nextCursor;
  } while (options.params.cursor);
}

If everything was done correctly, you should receive a response similar to this. The number of services and their names may vary depending on your organization:

> Fetching services...
Total services:  1
Service names:  [ 'Service 1' ]
Next cursor:  eyJwYWdlIjoyLCJsaW1pdCI6MX0=
> Fetching services...
Total services:  1
Service names:  [ 'Service 2' ]
Next cursor:  eyJwYWdlIjozLCJsaW1pdCI6MX0=
> Fetching services...
Total services:  1
Service names:  [ 'Service 3' ]
Next cursor:  eyJwYWdlIjo0LCJsaW1pdCI6MX0=
> Fetching services...
Total services:  1
Service names:  [ 'Service 4' ]
Next cursor:  null

More Complex Example

In this next example, we will create a custom workspace and populate it with some sample data.

Although Admina supports over 300 SaaS integrations, customers also have the option to create custom workspaces and manage the data within them. Combined with the Public API, this provides an easy way to automate processes. A good use case for this is managing SSO applications inside your Identity Provider (IdP).

We will be using the following three endpoints:

POST https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/workspaces/custom (API Reference)
POST https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/workspace/{workspaceId}/accounts/custom (API Reference)
GET https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/services/{serviceId}/accounts (API Reference)

First, let's create a custom service with a custom workspace. We’ll use POST https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/workspaces/custom (API Reference), which allows us to create a new custom workspace (and service).

Let's check out the code!

// We use Axios in our example, but feel free to choose your favorite library
//
// npm install axios --save
import axios from "axios"; // ESM
// const axios = require("axios"); // CJS

main();
async function main() {
  const orgId = encodeURIComponent("<YOUR ORG ID>"); // not required for numbers, but good practice
  const token = "<YOUR API KEY>";
  const options = {
    method: "POST",
    url: `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/workspaces/custom`,
    headers: {
      accept: "application/json",
      authorization: `Bearer ${token}`,
    },
    // Data will be automatically stringified as JSON
    data: {
      // Please see https://admina-docs.readme.io/reference/publiccreatecustomworkspace
      // It describes all fields and their role in the request
      serviceMasterName: null,
      serviceId: null,
      serviceName: "My Custom Service",
      serviceUrl: "https://example.com",
      workspaceName: "My Custom Workspace",
    },
  };

  const response = await axios.request(options);
  console.log(response.data);
}

If everything was done correctly, you should receive a response similar to this (we've omitted a few fields for readability):

{
  service: {
    id: 1000001,
    name: 'My Custom Service',
    url: 'https://example.com',
		// ...
  },
  workspace: {
    id: 18,
    serviceId: 1000001,
    authenType: null,
    workspaceName: 'My Custom Workspace',
    aggreKey: 'My Custom Workspace',
		// ...
    service: {
      id: 1000001,
      name: 'My Custom Service',
      url: 'https://example.com',
			// ...
    },
  },
  isNewService: true
}

Next, let's add some accounts!

First, make note of the workspace ID and service ID created in the previous request. In this example, the workspace ID is 18, and the service ID is 1000001. You will need these for the next request.

We will be using POST https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/workspaces/custom (API Reference), which allows us to add, update, or remove accounts in our custom workspace.

Let's check out the code:

// We use Axios in our example, but feel free to choose your favorite library
//
// npm install axios --save
import axios from "axios"; // ESM
// const axios = require("axios"); // CJS

main();
async function main() {
  const orgId = encodeURIComponent("<YOUR ORG ID>"); // not required for numbers, but good practice
  const workspaceId = encodeURIComponent("<YOUR WORKSPACE ID>"); // not required for numbers, but good practice
  const token = "<YOUR API KEY>";
  const options = {
    method: "POST",
    url: `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/workspace/${workspaceId}/accounts/custom`,
    headers: {
      accept: "application/json",
      authorization: `Bearer ${token}`,
    },
    // Data will be automatically stringified as JSON
    data: {
      // Please see https://admina-docs.readme.io/reference/publicsavecustomaccounts
      // It describes all fields and their role in the request
      create: [
        {
          email: "foo@example.com",
          displayName: "Foo Bar",
          userName: "foo.bar",
          roles: ["Foo", "Bar"],
          licenses: ["Baz"],
          twoFa: true,
        },
      ],
      update: [],
      delete: [],
    },
  };

  const response = await axios.request(options);
  console.log(response.data);
}

If everything was done correctly, you should receive an empty object in the response: {}.

🚧
Note
Changes to custom workspaces are performed asynchronously, so there may be a delay before you can see your changes.

Now, let's view the accounts that we added!

We will be using GET https://api.itmc.i.moneyforward.com/api/v1/organizations/{organizationId}/services/{serviceId}/accounts (API Reference). This endpoint allows us to list all accounts in a service, and by using filters, we can view all accounts belonging to a specific workspace. It also supports many more filtering options.

Let's check out the code!

// We use Axios in our example, but feel free to choose your favorite library
//
// npm install axios --save
import axios from "axios"; // ESM
// const axios = require("axios"); // CJS

main();
async function main() {
  const orgId = encodeURIComponent("<YOUR ORG ID>"); // not required for numbers, but good practice
  const serviceId = encodeURIComponent("<YOUR SERVICE ID>"); // not required for numbers, but good practice
  const workspaceId = "<YOUR WORKSPACE ID>";
  const token = "<YOUR API KEY>";
  const options = {
    method: "GET",
    url: `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/services/${serviceId}/accounts`,
    headers: {
      accept: "application/json",
      authorization: `Bearer ${token}`,
    },
    // parameters will be automatically encoded and included in the URL as query parameters
    params: {
      // Please see https://admina-docs.readme.io/reference/publicgetserviceaccounts
      // It describes all fields and their role in the request
      workspaceIds: [workspaceId],
    },
  };

  const response = await axios.request(options);
  console.dir(response.data, { depth: 3 });
}

If everything was done correctly, you should receive a response similar to this (we've omitted a few fields for readability):

{
  meta: { nextCursor: null },
  items: [
    {
      id: '18#aggre-user#foo@example.com',
      identityId: 'X2JD0IZK8Q',
      displayName: 'Foo Bar',
      email: 'foo@example.com',
      roles: [ 'Foo', 'Bar' ],
      status: 'active',
      employeeStatus: 'active',
      employeeType: 'full_time_employee',
      employeeManagementType: 'managed',
      twoFa: true,
      licenses: [ 'Baz' ],
      uniqueKey: 'aggre-user#foo@example.com',
      lastActivity: null,
      isInactive: false,
      workspace: {
        id: 18,
        serviceId: 1000001,
        workspaceName: 'My Custom Workspace',
        aggreKey: 'My Custom Workspace',
        // ...
      },
      costs: []
    }
  ]
}

And that's it!

Once you've worked through these examples, be sure to explore the full range of functionality our API offers by trying out other endpoints. For more detailed information and best practices, consult the documentation links below:

Authentication page for securely accessing the API.
Errors page for handling and troubleshooting any issues.
Pagination page to manage large datasets efficiently.
Need Help? page if you require additional assistance or have questions.

The documentation is designed to help you get the most out of our API, so don't hesitate to refer back as you continue to build your integration. Happy coding!

Step 3: API Testing

Our documentation site offers built-in API testing functionality. You can access any REST API endpoint directly through the docs and test it by providing your API key and filling in the required fields. It lists all the required and optional fields, expected schema and output. This feature allows you to quickly validate requests and explore the API without needing to set up an external environment.

To test an endpoint:

Browse the API Reference and select an endpoint.
Fill in the required parameters and input your API key in the provided field.
Execute the request and review the response directly in the browser.

Additionally, after testing the API, you can export a sample code snippet for the request in various programming languages, such as Python, JavaScript, Ruby, and more. This allows you to integrate the API call into your own application quickly.

You can access the latest OpenAPI specification here, allowing you to import it into your favorite tools, such as Postman.