SuiteCRM v8 API Documentation

SuiteCRM Forum - English Language SuiteCRM General Discussion
1

I’ve looked everywhere for some sort of documentation about how to FULLY address and work with the newer (v8) SuiteCRM API and I’m coming up empty handed.

The “documentation” that is available on the docs.suitecrm.com site is only about 5% of what’s needed to do anything with the API - it SORT OF gives you an idea of what you might be able to do but lacks any specifics and I questioned why it even exists as it did more to confuse me but I suspect maybe it’s being worked on… Until it’s done however, i’d love to get a PDF or something of all the v8 API methods so I can write code to interact with them.

I’ve been able to authenticate to my suiteCRM server just fine and then subsequently probe some very simple data but without any docs that specifically address what each {module} is named, does, the methods, how you interact with it, and required parameters, etc. i’m dead in the water.

Can anyone help me out?

Thanks,
Skip

2

Sorry, I don’t know much about the API, but I’ll try to help anyway.

I wish the people from the Community that have working API code would contribute a bit more to the Documentation, I agree with you it needs expansion.

Does GET /api/v8/modules/meta/list work?

I think this is the list of modules that counts for the API, the $moduleList global:

3

Hey,
have you seen the descriptions in Api\docs? There is a postman example and a swagger file describing the interface.

E:

swagger 
{
  "openapi": "3.0.0",
  "info": {
    "title": "SalesAgility REST API",
    "version": "8.1",
    "contact": {
      "name": "Support",
      "url": "https://suitecrm.com/forum"
    },
    "license": {
      "name": "GNU AFFERO GENERAL PUBLIC LICENSE VERSION 3",
      "url": "https://github.com/salesagility/SuiteCRM/blob/master/LICENSE.txt"
    }
  },
  "servers": [
    {
      "url": "http://localhost/forkedSuite/Api/V8"
    }
  ],
  "paths": {
    "/module/{moduleName}/{id}": {
      "get": {
        "tags": [
          "Module"
        ],
        "description": "Returns a bean with the specific ID",
        "parameters": [
          {
            "name": "moduleName",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Contacts"
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "b13a39f8-1c24-c5d0-ba0d-5ab123d6e899"
          },
          {
            "name": "fields[Contacts]",
            "in": "query",
            "description": "Filtering attributes of the bean",
            "schema": {
              "type": "string"
            },
            "example": "name,account_type"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Module"
        ],
        "description": "Delete a bean with specific ID",
        "parameters": [
          {
            "name": "moduleName",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Contacts"
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "b13a39f8-1c24-c5d0-ba0d-5ab123d6e899"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/module/{module}": {
      "get": {
        "tags": [
          "Module"
        ],
        "description": "Returns a collections of beans",
        "parameters": [
          {
            "name": "module",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Contacts"
          },
          {
            "name": "fields[Contacts]",
            "in": "query",
            "description": "Filtering attributes of each bean",
            "schema": {
              "type": "string"
            },
            "example": "name,account_type"
          },
          {
            "name": "page[size]",
            "in": "query",
            "description": "Number of beans showed in a page",
            "schema": {
              "type": "integer"
            },
            "example": "4"
          },
          {
            "name": "page[number]",
            "in": "query",
            "description": "Number of a page",
            "schema": {
              "type": "integer"
            },
            "example": "4"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting the bean list based on this parameter. Ascending by default, but if sort is prefixed with a minus (U+002D HYPHEN-MINUS, '-'), sort will be descending",
            "schema": {
              "type": "string"
            },
            "example": "-name"
          },
          {
            "name": "filter[operator]",
            "in": "query",
            "description": "Filtering the bean collection and using it between two or more conditions as logical operator. Only one level conditions are supported so far. Supported operators: AND, OR",
            "schema": {
              "type": "string"
            },
            "example": "AND"
          },
          {
            "name": "filter[name][eq]",
            "in": "query",
            "description": "Filtering the bean collections by conditions. The [name] is the  bean's property, the [eq] is a comparison operator. Supported operators: EQ, NEQ, GT, GTE, LT, LTE",
            "schema": {
              "type": "string"
            },
            "example": "John Doe"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/module": {
      "post": {
        "tags": [
          "Module"
        ],
        "requestBody": {
          "description": "Create a module record. If ID is not set, it will be created automatically. Attributes is optional, if the new bean will be set with certain, valid properties",
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "example": {
                  "data": {
                    "type": "Accounts",
                    "id": "86ee02b3-96d2-47b3-bd6d-9e1035daff3a",
                    "attributes": {
                      "name": "Account name"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      },
      "patch": {
        "tags": [
          "Module"
        ],
        "requestBody": {
          "description": "Update a module record. Type and ID are required, attributes have to be valid",
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "example": {
                  "data": {
                    "type": "Accounts",
                    "id": "86ee02b3-96d2-47b3-bd6d-9e1035daff3a",
                    "attributes": {
                      "name": "Another account name"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/module/{moduleName}/{id}/relationships/{relationship}": {
      "get": {
        "tags": [
          "Relationship"
        ],
        "description": "Get relationship of a bean",
        "parameters": [
          {
            "name": "moduleName",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Accounts"
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "11a71596-83e7-624d-c792-5ab9006dd493"
          },
          {
            "name": "relationship",
            "in": "path",
            "description": "The name of the relationship related to the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "contacts"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/module/{moduleName}/{id}/relationships": {
      "post": {
        "tags": [
          "Relationship"
        ],
        "parameters": [
          {
            "name": "moduleName",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Accounts"
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "11a71596-83e7-624d-c792-5ab9006dd493"
          }
        ],
        "requestBody": {
          "description": "Add relationship to a module. The type is the name of the relationship",
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "example": {
                  "data": {
                    "type": "contacts"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/module/{moduleName}/{id}/relationships/{relationship}/{relatedBeanId}": {
      "delete": {
        "tags": [
          "Relationship"
        ],
        "description": "Delete relationship between 2 modules",
        "parameters": [
          {
            "name": "moduleName",
            "in": "path",
            "description": "Name of the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Contacts"
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "b13a39f8-1c24-c5d0-ba0d-5ab123d6e899"
          },
          {
            "name": "relationship",
            "in": "path",
            "description": "The name of the relationship related to the module",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "contacts"
          },
          {
            "name": "relatedBeanId",
            "in": "path",
            "description": "ID of the related module",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "11806811-0b4b-fcdd-268b-5b2260e68333"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "BAD REQUEST"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    },
    "/logout": {
      "post": {
        "tags": [
          "Logout"
        ],
        "description": "Logging out",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "UNAUTHORIZED"
          }
        },
        "security": [
          {
            "oauth2": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "password": {
            "tokenUrl": "http://localhost/forkedSuite/Api/access_token",
            "scopes": {}
          }
        }
      }
    }
  }
}
4

Hi @skip,

Welcome to the Community! :tada:

I assume you mean V8 not v8 (Yes they are different) as little v8 is now deprecated. Additional and somewhat fuller documentation can be found within the code itself.

Navigating to Api/docs/swagger/swagger.json and copy its contents into a swagger editor for example https://editor.swagger.io/

Let me know if there any further questions and remember that the docs site is always open to contributions if you find any knowledge you believe should be shared there.

8

No, that path of -> /api/v8/modules/meta/list returns: “File not found.”

When I try: /Api/v8/modules/meta/list - no dice either - it returns:

Not Found

The requested URL was not found on this server.

When I try: /Api/V8/modules/meta/list - returns:

Page Not Found

The page you are looking for could not be found. Check the address bar to ensure your URL is spelled correctly. If all else fails, you can visit our home page at the link below.

[Visit the Home Page]

The thing that’s strange is that each URL seems to return a slightly different error message, is that an indication of anything else going on possibly?

Thanks,
Skip

9

yep - seem them but this is useless without knowing what the modules are, or the ways to call them specifically in each instance.

To do something as trivial like, synchronizing an external system with e-mail addreses and marketing status (on/off) type data - seems next to impossible when it should in fact be like the MAIN use case for using the API from everything I can imagine using a CRM for.

There’s nothing anywhere online explaining anything along the lines of how to Query a prospect list, see who the members are, then add other targets to that list if they’re not already - it requires just a few API calls in theory but I’m obviously stabbing in the dark with no idea of method calls and what data to push to things, etc.

Structure, sure that’s obvious - but beyond that - what to do is beyond me.

can anyone help?

thanks,
Skip