ALM How to Get Started Using the ALM REST API

Software Testing Published on:


With the release of ALM 11, HP now offers an API that allows the user to interact with QC/ALM using REST. Rather than writing OTA code, one can now accomplish some of the same functionality using a browser as a client – no code writing needed.

Of course, you can also use tools like soapUI to work with ALM or create custom applications using languages like VBscript, C# and Java that interact with ALM.

But to keep it simple, we'll start by taking a look at how to get started using your browser as a client.

Getting started using your browser as a client

The first thing you'll need to do before using the ALM REST API is to authenticate your user. You can do this by obtaining a session cookie which returns a token that, by default, times out after one hour of inactivity.

Authenticate your user

1. Determine whether your user is currently authenticated by navigating to:


If your user is not currently authenticated, you'll get an HTTP Status Code 401.

2. To authenticate your user, navigate to:


3. Enter the ALM login name and password you want to authenticate:


4. If your ALM user is authenticated, you'll get the following XML:


How to READ an ALM defect

You should now be authenticated. Cool! Next, let's make sure we're able to retrieve the very first defect in ALM.


1. To READ an ALM defect record, place the following URL (using your ALM instance info) into your browser:




2. The first defect should populate your browser with its XML info:



Although our example returned info for a defect in ALM, you can also read info for the other ALM entities, which are:


  • Defects
  • Resources
  • Requirements
  • Tests
  • Test lab

For example – if we wanted to read the first requirement info from ALM, we would simply change the defect URL we used to point to requirements instead of defects:



Other common tasks you can perform

We saw in the example above how easy it is to READ an existing record in ALM. Some other common tasks that can be performed using the ALM API are:


  • Create
  • Delete
  • Read
  • Update

That should be enough info to get you started using the ALM REST API. For more info, be sure to check out HP's ALM REST API doc – and as always, drop me a line with any questions or comments!

61 responses to “ALM How to Get Started Using the ALM REST API”

  1. Hi Joe,

    I would like to understand how do I perform database queries using REST API. Similar to using the tdconnectin.command object, used to query multiple tables, is there a way to accomplish this using REST?


  2. Hi,

    I am trying to access the rest api via python. However, I seem to be unable to authenticate. Would you have any sample python code that I can use as an example?

  3. Hi Joe,
    As mentioned in the topic “ALM 11 – GETTING STARED WITH REST API ” , about reading a defect. I need a detailed steps for deleting and updating a defect or any entity. can any one help me in this?

  4. Hi Joe,

    I am trying to access the URL with our ALM path, however i am seeing the error “The requested resource (/qcbin/rest/is-authenticated) is not available”. Please help me with this. Thanks!

    Jayashree SN

  5. Hi Joe,

    Great site and good articles. I am using QC 11.52 and trying to write a VAPI-XP automated test case using perl script and calling a java program through it. I am using the VAPI test wizard but it asks me to download BSF (Bean Scripting Framwork). I have already downloaded it but still it and placed the path in the classpath of environment variable but still it gives me the same JVM not founf error. Can you please let me know if it is even possible to do what I am doing and if yes what am I missing.

    Require your immediate help.


    • Hi Atul I have not seen this issue. If you go to a command prompt and type java -version does it find the java version info? If not then it is definitely a path issue not being properly defined in you environment variables. What is throwing the JVM not found error ALM?

  6. Hi Joe,
    Thanks for this wonderful Post.I need a solution for this.
    I need to pull defects that are not linked to any Test cases alone using Rest API.I tried several ways like, 1.Putting cross filter with Defects and Test Set
    2. http://ALM SERVER/qcbin/rest/domains/xxx/projects/YYY/defects/1/defect-links.This seems to work for only 1 defect.How can I retrieve the same info for a group of defects?
    CAn any one help me plz

      • Hi Joe,

        Thanks for your wonderful post.

        By following your examples, I am able authenticate and get the defect information in xml format, but my requirement is to access a defect directly from a URL in HPALM itself.

        Can you please suggest a way?

        Appreciate your help with this.

        Thanks & Regards,

  7. Thanks joe, your document helped me to achieve my first step of authenticating with ALM 11.0, i was struggling for such a document for almost 3 weeks.
    I need your help in the below query. I authenticated successfully but later when i used the below query to GET data it was saying unauthorized. Can you please help me why was it saying unauthorized here.

  8. Please guide me the details step to configure soapui 4.6 with ALM 11 ??

    For example how to do a Post/Get request for defect entity, i am getting authentication error as “HTTP Status 401 – An Authentication object was not found in the SecurityContext” even though i am passing all the authentication parameters with the soap request.

  9. I’m having trouble with the API. I can insert a valid defect fine, but the problem arises when I try to insert a defect with a problem, like for example the data I am trying to insert is longer than the ALM field can handle. Instead of rejecting the input, the API allows the attempt, then creates an empty defect with only the Defect ID. Obviously I will try not to insert invalid data, but you never know if a field will be changed or deleted on the ALM side. Is there some way to tell ALM to reject my API input instead of creating an empty defect?

  10. Hi,

    Please help!!!!!

    Am working on this REST API. I have a problem now and need to know whether it is possible to read tables using REST API.
    I have a table “common_settings” related to a project, it contains all the settings related to that project.

    Thanks in advance.

  11. Hi Dear Friend,
    To login in HP/ALM using REST, I am using following code.
    Response response=given().that().parameter(“j_username”,userName).parameter(“j_password”, password).when().get(“http://x-xxxx.YY:YYYY/qcbin/rest/is-authenticated?login-form-required=y”).then().extract().response();
    But i am not able to. I am getting login page as reponse and not XML that you told. If i logged in manually, I am getting XML. Please help me out asap, others too who all are visitng this page.
    Thanks in advance.

  12. I have found that your comments where the most helpful if any thing that I have found on this subject.

    I have a question. When I connect through the browser and run the following query and get a single response.
    but when I do the same thing through my java app it return the complete collection.

    Any ideas?

  13. Hi Joe,

    It looks like the location for that HP ALM Rest Wrapper has been moved as it now comes upwith not found on codeplex. Do you have a copy or know the location for the new site?

  14. Hi Joe,

    Could you please tell me how to update a test status in test lab using java code so that i can update the test status after execution of my junit tests.

    please help

    Vineeth Varghese

    • Hi Joe,

      We have a requirement to update the test case id in QC after executing our selenium automation test cases using Bamboo. Could you please help me to get some idea on doing this. Please advise

      Vineeth Varghese

  15. I am trying to create a testcase in QC using REST, I refered the documentation examples “createDeleteExample” where it is there for “requirements”. I tried the similar way for creating test, “login ” happens, but throws exception during “post” operation. Response code returned is “500” – Internal server error.
    i have used in the request header the following xml schema
    String entityToPostXml =
    + Double.toHexString(Math.random()) + “”);
    Why that exception return code”500″ occured?

  16. How do I run the REST query using UFT? I logged into ALM beforehand as described but receive the error below. Through a browser the queriy works, but not through UFT. UFT doesn’t seem to recognize the cookie.


    Error Step ‘Method4’ : HTTP/1.1 401 Authentication failed. Browser based integrations – to login append ‘?login-form-required=y to the url you tried to access.

  17. Quality Center is a powerfull testing process tool. Including as well defect managment.

    As a QA manager, my main problematic was to manage several defects coming from many QC projects. And so, how to gather all these defect in an unic view.
    Other topic, developers working with ubuntu or any else OS other than internet explorer that should be able to the list of defect…

    Got it with QC DASHBOARD!

    A web client for Quality Center, runnable from any web browser (Opera, Firefox, Chrome), which also provides an responsive and unified view for all my Quality Center projects.
    Simple and clear web interface, it’s also usefull to get dedicated business views, for instance to prepare my next releases, display directly latest created defect and many other features.

    Let’s share it :

  18. Hi,

    I am trying to access the rest API via python. However, I seem to be unable to authenticate. Would you have any sample python code that I can use as an example?
    I want to download the defects from ALM to Excel sheet by applying filters.

  19. Can you please let me know how to update a requirement status using rest api.The example shows for read.

  20. Hi Joe,

    Really it is a good article.

    I am trying to login ALM,and navigate to test lab ,then click on test set ,needs to execute using RUN button in test lab is it possible?

    if so please suggest me how to do this using automation .


  21. I am running some tests and want to create defects on HP QC using the REST APIs – programatically.

    Let’s say some of the tests fail every day and it will take 30 days for it to be fixed. I want to create a defect on the first day, and NOT on subsequent runs. How can I know that a defect has been created (or not created).

  22. Specflow and HP ALM Integration
    I am looking for a solution on Specflow and HP ALM Integration.
    Can anyone help me out on this ?

  23. Hi

    I have the following issue and need a solution

    1. I want to pull the Test case Execution count using REST API based on the Test Lab Folder name. There can be many test sets inside that test lab folder and even test folders.
    Eg: Test Folder 1\Test Folder 2\Test Folder 3\Test Set 1

    I need to pull the execution count ( No. of Pass,Fail,No Run etc.,) by giving the parent test lab folder (Test Folder 1).

    2.I want to pull the ALM defects using REST API . I have many Favorites in my ALM as Public and Private . Is there a way i can pull the those using REST API ?

    3. I want to pull the number of test cases linked to a defect using REST API . I am able to pull the defects but not the linked test cases

    Can you please help me with these ?

  24. Did anyone tried using CURL and get the authentication?

    Basically here’s what I tried

    Step 1: Tried below and get response

    -> curl http://QCURL/qcbin/rest/is-authenticated

    Error 401 Authentication failed. Browser based integrations – to login append ‘?login-form-required=y’ to the url you tried to access.

    HTTP ERROR 401
    Problem accessing /qcbin/rest/is-authenticated. Reason:
    Authentication failed. Browser based integrations – to login append ‘?login-form-required=y’ to the url you tried to access.Powered by Jetty://

    Step 2: Tried below and didnt get any response back.

    -> curl http://QCURL/qcbin/rest/is-authenticated?login-form-required=y


    How to pass user name and password using CURL

  25. here is a complete reference by HP

    what this reference is missing is that after you have authenticated you must do a POST to /qcbin/rest/site-session this will give you two cookies XSRF-TOKEN and QCSESSION see here

    Once you have gotten those two cookies you can delete, update and create entities.

    I hope this helps.

  26. Hi friends, I need some help as I’m going crazy trying to solve a problem.

    In a Visual Basic macro I firstly authenticate an user and then I get session cookies, as specified in the previous post. After that, I launch some queries to get data from test cases, defects, and so other QC instances.

    My problem is that each one of these queries creates a connection (visible in ALM – Site Administration Site Connections). When the macro execution finishes, these connections remain opened…. and last week this produced a (big) problem in the server’s performance.

    I’ve implemented in the macro the logic for using “/authentication-point/logout” that releases the authentication cookie and it works because if I run a query after it the server returns 401. The problem is that this does not clear connections in the server.

    Do you have any idea?

    Thanks in advance for your answers.

  27. I’m trying to add a run in ALM using the REST API. I can successfully add a test run in the Test Runs page of ALM but back on the Test Lab page I have been unsuccessful. In order to update the test cases in the test set which is displayed on the Test Lab page I need to know the testcycl-id. There is at present no way to get that information. Does anyone have any idea how to get the testcycl-id?

  28. Get target-rel date
    How to get the target-rel date in defects .I am using java to read the defects and converting to jaxb clasess to map the attributes.Now unable to get the target-rel date because in “target-rel ” it is having the value as string and date is in “ReferenceValue”.I want to raed the both the values like ReferenceValue and value inside the target-rel .Please suggest.Thank You

  29. Hi,

    After authentication , i tried to get First Defect , and i am getting error message.

    “Exception Id: qccore.general-error”

  30. Hi, I am totally new in IT profession, my Manager has asked me to automate task of passing test cases and attaching the evidences to tests in test lab using VB scripting/macros. Can you please help me?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.